Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
Bango Developer
  1. Bango Resale
  2. For resellers
  3. Managing entitlements
  4. Retrieving a single entitlement

Retrieving a single entitlement

Fetching the current details for an existing entitlement

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. To find out the current details of an entitlement, you make a GET request to the Bango Resale API, specifying the entitlement ID. (You can also retrieve some or all of a user's entitlements with a single request.)

The API response is a structure that contains:

  • A response code, indicating the result of the request. Use this code to determine what to do next.
  • For HTTP 200 responses, the entitlement record, including any custom data you've supplied.
Sequence diagrams
Successful retrieval

The Bango Platform successfully returns the entitlement details.

Failed retrieval

The Bango Platform fails to return entitlement details.

Skeleton code

Here's some sample code in a C/Java-like language: adapt this code to your needs. Use the same API endpoint prefix with test credentials and with production credentials.

function get_entitlement (entitlement_id) {
    // *Always* use this endpoint prefix for the Bango Resale API.
    const base_url = "";

    // This is what we're trying to find.
    let entitlement = null;

    try {
        // GET UTF-8 JSON to the Bango Resale API and parse the JSON response
        let response = rest_client_call({
            method: "GET",
            url: base_url + "entitlement/" + entitlement_id,
            headers: {
                "Authorization": get_authorization_header(),

        // The responseCode tells us the result.
        switch (response.responseCode) {
            // Success
            case "OK":
                entitlement = response;

            // Failures
            // These may indicate issues in your code, not the Bango Platform.
            case "BAD_REQUEST": // Invalid request
            case "UNAUTHORIZED": // Check your credentials
            case "NOT_FOUND": // Invalid entitlement ID
            case "TOO_MANY_REQUESTS": // Request limit reached: try again later
                throw "Unable to retrieve entitlement";

            // Bango Platform issues
            // These likely indicate transient problems.
            // In production code, you might want to try the request again
            // after a delay, ultimately falling back to an error state.
            case "INTERNAL_ERROR":
            case "SERVICE_UNAVAILABLE":
                throw "Bango Platform unavailable";

            // This might indicate Bango has added a new response code.
            // Check the documentation again.
                throw "Unrecognized response code";

    } catch (exception) {
        // Production code might want to notify the reseller in some way,
        // and/or log full details of the exception for later analysis,
        // and degrade gracefully for the user.
        output("An error occurred!");

    // null if entitlement not retrieved.
    // If retrieved, will have an entitlementId, status, and other properties:
    // see API reference.
    return entitlement;
Which request parameters should I set?

The only parameter is the entitlement ID, passed in the path of the request URL.

What are all the possible API response structures?

All responses contain a responseCode string that indicates the result of the request. Use responseCode to determine how to react.

On success, responseCode is OK and other properties describe the entitlement. Here's an example response:

    "responseCode": "OK",
    "responseMessage": "Success",
    "entitlementId": "a25100b8-4e0c-4e37-b921-cac9cb1e930f",
    "activationCode": "",
    "customerIdentifier": "my-customer-identifer-123456",
    "productKey": "30_DAYS_MUSIC",
    "entitlementDisplayName": "30 days of Bango Music",
    "offerKey": "BUNDLE",
    "merchantAccountKey": "BANGO",
    "status": "ACTIVE",
    "dateCreated": "2017-07-28T14:15:03Z",
    "dateActivated": "2017-07-28T14:30:05Z",
    "dateExpiry": null,
    "dateEnded": null,
    "dateSuspended": null,
    "dateResumed": null,
    "dateLastUpdated": "2017-07-28T14:30:05Z",
    "notificationUrl": "",
    "extensionData": {
        "price": "9.99",
        "currencyIso3": "GBP",
        "channelType": "WEB_PROMOTION",
        "channelSource": ""
        "campaignKey": "SUMMER_PROMO",
        "referrer": "SEARCH_ENGINE"

See Bango Resale / For resellers / Reseller API reference / Reseller API reference overview for detailed information on all responses.

Copyright © 2000–2021 Limited