Create an entitlement

curl --request POST \ --url https://resale.api.sandbox.bango.com/v1/entitlement \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data ' { "customerIdentifier": "123456789", "merchantAccountKey": "BANGO_US", "productKey": "MUSIC", "notificationUrl": "https://notifications.bango.com" } '

{ "customerIdentifier": "123456789", "sharedCustomerId": "414b3019-0c28-4d14-9c5f-6217b8bd1e3e", "bangoUserId": "2147483647", "merchantAccountKey": "BANGO_US", "productKey": "MUSIC", "entitlementDisplayName": "30 day free trial for Bango Music", "offerKey": null, "activationCode": null, "dateCreated": "2024-06-22T17:35:38.92Z", "dateActivated": "2024-06-22T17:35:59.90Z", "dateEnded": "0001-01-01T00:00:00Z", "dateExpiry": "0001-01-01T00:00:00Z", "dateAutoSuspend": "0001-01-01T00:00:00Z", "responseCode": "OK", "responseMessage": "Success", "status": "ACTIVE", "externalEntitlementId": "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63", "extensionData": { "customField1": "value1", "customField2": "value2" }, "parameters": null, "extraInformation": { "communicationInformation": { "emailAddress": "example@bango.com", "msisdn": "441234567890" }, "clientDevice": { "type": "STB", "id": "bc449c9e-406f-4399-a3ff-8671a27ac410", "typeId": "P49AJFND8NFN23NANGAJG", "modelName": "STB Model X7", "modelNumber": "IAH45IAOF/5", "serialNumber": "JHFJHA43JNFA9393GFD", "osType": "Linux", "osVersion": "10.3.8", "macAddress": "4A-0F-99-F2-D3-DD", "browser": "Chrome" }, "source": { "channelType": "Retail", "campaignRef": "SUMMER_PROMO", "referrer": "SEARCH_ENGINE", "bundleId": "BundleABC123", "country": "United Kingdom", "region": "CB1 3ED", "brand": "BrandA" } } }

Authorizations

x-api-key

string

header

required

Headers

X-RequestIdentifier

string<uuid>

Optional identifier to support idempotency

x-request-id

string

Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.

x-operation-id

string

Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.

Body

application/json

customerIdentifier

string

required

Unique, immutable user identifier

Example:

"123456789"

merchantAccountKey

string

required

Unique identifier for the content provider

Example:

"BANGO_US"

productKey

string

required

Unique identifier for the product/offer

Example:

"MUSIC"

notificationUrl

string<url>

required

The endpoint where Bango will send all notifications regarding this entitlement

Example:

"https://notifications.bango.com"

offerKey

string

Entitlement offer identifier

Example:

"BUNDLE"

externalEntitlementId

string

Unique identifier for the entitlement provided by the reseller. If the previous attempt to create an entitlement failed, this value can be reused.

Example:

"124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"

entitlementDisplayName

string

Entitlement display name, seen in reports.

Example:

"30 day free trial for Bango Music"

dateExpiry

string<date>

If set, Bango will schedule a termination request to the content provider on this date. Date format must be ISO 8601

Example:

"2024-12-05T07:46:52.000Z"

dateAutoSuspend

string<date>

If set, Bango will schedule a suspension request to the content provider on this date. Date format must be ISO 8601

Example:

"2024-09-05T07:46:52.000Z"

extensionData

object

Custom key value pairs

Show child attributes

extraInformation

object

Show child attributes

Response

Entitlement created and activated successfully

entitlementId

string

Unique identifier representing a specific entitlement

customerIdentifier

string

Unique, immutable user identifier

Example:

"123456789"

sharedCustomerId

string<uuid>

Bango generated id shared between reseller and merchant for this customer (contact support for setup)

Example:

"db2001b5-fde5-4654-9ecd-b3b04ba8f025"

merchantAccountKey

string

Unique identifier for the content provider

Example:

"BANGO_US"

productKey

string

Unique identifier for the product/offer

Example:

"MUSIC"

notificationUrl

string<url>

The endpoint where Bango will send all notifications regarding this entitlement

Example:

"https://notifications.bango.com"

offerKey

string

Entitlement offer identifier

Example:

"BUNDLE"

externalEntitlementId

string

Unique identifier for the entitlement provided by the reseller. If the previous attempt to create an entitlement failed, this value can be reused.

Example:

"124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"

entitlementDisplayName

string

Entitlement display name used in reports.

Example:

"30 day free trial for Bango Music"

dateCreated

string<date>

Timestamp for the creation of the entitlement

Example:

"2024-06-22T17:35:38.920Z"

dateActivated

string<Date>

Timestamp provided by the content provider when the entitlement is activated

Example:

"1901-01-01T00:00:00.000Z"

dateEnded

string<date>

Timestamp for when the entitlement terminated

Example:

"1901-01-01T00:00:00.000Z"

dateSuspended

string<date>

Timestamp for when the entitlement was suspended

Example:

null

dateResumed

string<date>

Timestamp for when the entitlement was last resumed

Example:

null

dateExpiry

string<date>

If set, Bango will schedule a termination request to the content provider on this date. Date format must be ISO 8601

Example:

"2024-12-05T07:46:52.000Z"

dateAutoSuspend

string<date>

If set, Bango will schedule a suspension request to the content provider on this date. Date format must be ISO 8601

Example:

"2024-09-05T07:46:52.000Z"

responseCode

string

Example:

"OK"

responseMessage

string

Example:

"Success"

parameters

object

Show child attributes

DVM APIs

Products

Offers

Consumer Offers

Entitlements

Notifications

Eligibility

Charge

Testing

Authorizations

Headers

Body

Response