Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
OK
Bango Developer
  1. Bango Resale API
  2. API reference

Entitlement creation API

Details of the API for requesting user access to merchant services

This page describes the method used to create an entitlement using the Bango Resale API. You can change many of the properties later: see Entitlement update API.

Every API request must comply with the requirements in Bango Platform / Connectivity and security. All request body parameters and responses are encoded as UTF-8 JSON objects.

Create an entitlement

POST https://resale.api.bango.net/v1/entitlement
Path parametersNone
Header parameters
Authorization string

Your Bango Resale API credentials encoded for HTTP Basic Authentication. See Bango Platform / Connectivity and security / Basic authentication.

X-RequestIdentifier string

A unique identifier for the request. If present, this ID is used for Bango Platform idempotency.

Query parametersNone
Body parameters
customerIdentifier string

A unique, persistent identifier for the user you want to activate the service for. This is an ID you've generated: the Bango Platform treats it as opaque.

merchantAccountKey string

The identifier for the merchant supplying the service you want to activate for the user. Bango owns these identifiers and makes them available to you as necessary.

productKey string

The identifier for the merchant service you want to activate for the user. Bango owns these identifiers and makes them available to you as necessary.

offerKey string

An identifier for the type of offer associated with the service being activated. Allowed values depend on the merchant and service. Bango owns these identifiers and makes them available to you as necessary.

entitlementId string

The unique ID to use for the entitlement. Omit to let the Bango Platform generate an ID (recommended).

If you try to reuse an ID, the Bango Platform responds with ALREADY_EXISTS (see below). However, you can use the same ID in test and in production if you need to.

Your own IDs will never clash with IDs of other resellers.

activationCode string

A merchant-dependent code that might be required. Omit unless the merchant requires it. Some merchants may generate their own code, overriding yours.

entitlementDisplayName string

A user-visible string representing the entitlement (recommended).

dateExpiry ISO 8601 string or null

ISO 8601 timestamp of the moment the user's entitlement to the service ends.

notificationUrl string

A URL the Bango Platform uses to POST you updates about this entitlement (recommended). See Bango Resale API / API reference / Asynchronous notifications.

extensionData object

An arbitrary collection of string keys and string values to associate with the entitlement. Bango recommends the following:

  • price: The amount you charge the user in each billing cycle.
  • currencyIso3: The ISO 4217 currency code for the price.
  • channelType: The channel used for the sale. Recommended values:
    • WEB_PROMOTION: Website promotion
    • POINT_OF_SALE: Physical store sale
    • SMS_PROMOTION: Promotion over text messaging
    • EMAIL_PROMOTION: Promotion over email
  • channelSource: Sale origin. Values depend on the channelType. For example, with WEB_PROMOTION, use the website URL.
  • campaignKey: The marketing campaign identifier. For example, SUMMER_PROMO.
  • referrer: The sale referrer. For example, SEARCH_ENGINE, CUSTOMER_RECOMMENDATION, or SOCIAL_MEDIA.

All keys and values must be strings. You can't use any other value types. This means you can't create arbitrary nested object or array structures.

Sample requests
Request an entitlement with typical parameters
POST https://resale.api.bango.net/v1/entitlement HTTP/1.1

{
    "customerIdentifier": "my-user-123456789",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productKey": "MUSIC_30D",
    "entitlementDisplayName": "30 days of Bango Music",
    "dateExpiry": "2017-09-30T23:59:59.999Z",
    "notificationUrl": "https://example.com/entitlement/notification",
    "extensionData": {
        "price": "9.99",
        "currencyIso3": "GBP",
        "channelType": "WEB_PROMOTION",
        "channelSource": "https://bango.com/promo",
        "campaignKey": "SUMMER_PROMO",
        "referrer": "SEARCH_ENGINE"
    }
}

Request an entitlement for the MUSIC_30D service of BANGO_ENTERTAINMENT, for user my-user-123456789. Entitlement to the service expires just before midnight UTC on the last day of September 2017. The Bango Platform posts asynchronous entitlement changes to https://example.com/entitlement/notification.

Specify a custom entitlement ID and extra data with the request
POST https://resale.api.bango.net/v1/entitlement HTTP/1.1

{
    "entitlementId": "my-custom-id-abcdef-fedcba",
    "customerIdentifier": "my-user-123456789",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productKey": "MUSIC_30D",
    "offerKey": "BUNDLE",
    "entitlementDisplayName": "30 days of Bango Music",
    "notificationUrl": "https://example.com/entitlement/notification",
    "extensionData": {
        "price": "8.99",
        "currencyIso3": "GBP",
        "channelType": "POINT_OF_SALE",
        "channelSource": "store-5407",
        "priceDiscretionaryDiscount": "1.00",
        "salesAdvisor": "indigoj"
    }
}

Request an entitlement for the MUSIC_30D service of BANGO_ENTERTAINMENT, for user my-user-123456789, using my own entitlement ID and specifying the BUNDLE offer. Entitlement to the service does not expire (as dateExpiry is omitted). The Bango Platform posts asynchronous entitlement changes to https://example.com/entitlement/notification. Some alternative extension data is included.

Response body
responseCode string

Result of the request. Possible values: OK, CLIENT_ACTION_REQUIRED, BAD_REQUEST, UNAUTHORIZED, NOT_AVAILABLE, ALREADY_EXISTS, TOO_MANY_REQUESTS, INTERNAL_ERROR, SERVICE_UNAVAILABLE. See sample responses for more information.

responseMessage string

A short human-readable message describing responseCode. Not for use by code.

parameters object2xx

For HTTP status 202, contains the property action describing what your code must do, and other parameters that depend on the action. See sample responses.

entitlementId string2xx

The unique, persistent ID of the entitlement.

status string2xx

The current status of the entitlement. On creation, an entitlement is always either ACTIVE or PENDING depending on merchant requirements. When responseCode is OK, status is ACTIVE. When responseCode is CLIENT_ACTION_REQUIRED, status is PENDING. See sample responses.

dateCreated ISO 8601 string2xx

ISO 8601 timestamp for the entitlement creation time.

dateActivated ISO 8601 string or null2xx

ISO 8601 timestamp for the entitlement's last activation time. null if the entitlement has never been active.

dateEnded ISO 8601 string or null2xx

ISO 8601 timestamp for when the entitlement was last canceled or revoked. null if never.

dateSuspended ISO 8601 string or null2xx

On creation, null.

dateLastUpdated ISO 8601 string2xx

ISO 8601 timestamp for the last time the entitlement was modified.

customerIdentifier string2xx

The value specified in the request.

merchantAccountKey string2xx

The value specified in the request.

productKey string2xx

The value specified in the request.

offerKey string2xx

The value specified in the request.

activationCode string2xx

The merchant's activation code, if applicable.

entitlementDisplayName string2xx

The value specified in the request.

dateExpiry ISO 8601 string or null2xx

The value specified in the request.

notificationUrl string2xx

The value specified in the request.

extensionData string2xx

The value specified in the request.

Sample responses
200OKEntitlement created and activated successfully
{
    "responseCode": "OK",
    "responseMessage": "Success",
    "parameters": {},
    "entitlementId": "a25100b8-4e0c-4e37-b921-cac9cb1e930f",
    "status": "ACTIVE",
    "dateCreated": "2017-08-31T14:15:03Z",
    "dateActivated": "2017-08-31T14:16:64Z",
    "dateEnded": null,
    "dateSuspended": null,
    "dateLastUpdated": "2017-08-31T14:16:64Z",
    "customerIdentifier": "my-user-123456789",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productKey": "MUSIC_30D",
    "offerKey": null,
    "activationCode": "",
    "entitlementDisplayName": "30 days of Bango Music",
    "dateExpiry": "2017-09-30T23:59:59.999Z",
    "notificationUrl": "https://example.com/entitlement/notification",
    "extensionData": {
        "price": "9.99",
        "currencyIso3": "GBP",
        "channelType": "WEB_PROMOTION",
        "channelSource": "https://bango.com/promo",
        "campaignKey": "SUMMER_PROMO",
        "referrer": "SEARCH_ENGINE"
    }
}

The Bango Platform successfully created the entitlement, and the merchant activated the service for the user. The entitlement status is ACTIVE.

202CLIENT_ACTION_REQUIRED: NAVIGATE_TO_URLEntitlement created successfully, now pending activation
{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client",
    "parameters": {
        "action": "NAVIGATE_TO_URL",
        "url": "https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f"
    },
    "entitlementId": "a25100b8-4e0c-4e37-b921-cac9cb1e930f",
    "status": "PENDING",
    "dateCreated": "2017-08-31T14:15:03Z",
    "dateActivated": null,
    "dateEnded": null,
    "dateSuspended": null,
    "dateLastUpdated": "2017-08-31T14:16:64Z",
    "customerIdentifier": "my-user-123456789",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productKey": "MUSIC_30D",
    "offerKey": null,
    "activationCode": "",
    "entitlementDisplayName": "30 days of Bango Music",
    "dateExpiry": "2017-09-30T23:59:59.999Z",
    "notificationUrl": "https://example.com/entitlement/notification",
    "extensionData": {
        "price": "9.99",
        "currencyIso3": "GBP",
        "channelType": "WEB_PROMOTION",
        "channelSource": "https://bango.com/promo",
        "campaignKey": "SUMMER_PROMO",
        "referrer": "SEARCH_ENGINE"
    }
}

The Bango Platform successfully created the entitlement. In this case the merchant requires the user to complete a process before activation (for example, signing up), so the Bango Platform returned response code CLIENT_ACTION_REQUIRED with parameters.action value NAVIGATE_TO_URL, and set the entitlement status to PENDING. Your code should ensure the user visits parameters.url, perhaps by programmatically opening that URL on their device.

Entitlements with status PENDING may change status to ACTIVATION_EXPIRED if the user does not complete the merchant process quickly enough (you may be able to reactivate these entitlements). When the user completes the process, the status may change to ACTIVE. The Bango Platform POSTs these status changes to the entitlement's notificationUrl.

400BAD_REQUESTInvalid API request
{
    "responseCode": "BAD_REQUEST",
    "responseMessage": "Invalid request."
}

The Bango Platform was unable to process the request. This indicates an implementation problem in your code. Check your productKey and notificationUrl are correct.

401UNAUTHORIZEDIP address or access credentials are invalid
{
    "responseCode": "UNAUTHORIZED",
    "responseMessage": "Invalid access credentials."
}

The Bango Platform didn't process the request as the supplied credentials were invalid, or the request was not from an authorized IP address. This indicates an implementation problem in your code or a configuration issue. See Bango Platform / Connectivity and security / Basic authentication and Bango Platform / Connectivity and security / IP whitelisting.

403NOT_AVAILABLEUnable to create entitlement for the service
{
    "responseCode": "NOT_AVAILABLE",
    "responseMessage": "No active entitlement routes found."
}

The Bango Platform didn't create the entitlement as the service described in the request is either not enabled for you to use, or has been temporarily disabled due to service issues. Contact Bango Support for more information.

409ALREADY_EXISTSEntitlement ID already in use
{
    "responseCode": "ALREADY_EXISTS",
    "responseMessage": "EntitlementId already exists."
}

The Bango Platform didn't create the entitlement as you're already using the entitlementId supplied in the request. Use a different ID.

429TOO_MANY_REQUESTSRequest limit reached
{
    "responseCode": "TOO_MANY_REQUESTS",
    "responseMessage": "Request limit reached. Please try again later"
}

The Bango Platform didn't process the request as you've sent too many requests recently. Try again later.

500INTERNAL_ERRORUnexpected server issue
{
    "responseCode": "INTERNAL_ERROR",
    "responseMessage": "The server encountered an unexpected condition."
}

The Bango Platform couldn't respond to the request. Try again later.

503SERVICE_UNAVAILABLEBango Platform undergoing maintenance
{
    "responseCode": "SERVICE_UNAVAILABLE",
    "responseMessage": "The server is undergoing maintenance."
}

The Bango Platform is undergoing maintenance and is not currently available. Try again later.

Copyright © 2000–2019 Bango.net Limited