> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/legacy/resale/reseller/entitlements/retrieve) 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

<AccordionGroup>
  <Accordion title="Successful retrieval">
    The Bango Platform successfully returns the entitlement details.

    <Frame>
      <img src="https://mintcdn.com/bango/s_PrfQYExYEfR0YB/images/image-34.png?fit=max&auto=format&n=s_PrfQYExYEfR0YB&q=85&s=08cd94abe590f7256bf9257d728ffd35" alt="Image" width="544" height="334" data-path="images/image-34.png" />
    </Frame>
  </Accordion>

  <Accordion title="Failed retrieval">
    The Bango Platform fails to return entitlement details.

    <Frame>
      <img src="https://mintcdn.com/bango/s_PrfQYExYEfR0YB/images/image-34.png?fit=max&auto=format&n=s_PrfQYExYEfR0YB&q=85&s=08cd94abe590f7256bf9257d728ffd35" alt="Image" width="544" height="334" data-path="images/image-34.png" />
    </Frame>
  </Accordion>
</AccordionGroup>

### 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.

```text theme={null}
function get_entitlement (entitlement_id) {
    // *Always* use this endpoint prefix for the Bango Resale API.
    const base_url = "https://resale.api.bango.net";

    // 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(),
            },
        }).from_json();

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

            // 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.
            default:
                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!");
        output(exception);
    }

    // null if entitlement not retrieved.
    // If retrieved, will have an entitlementId, status, and other properties:
    // see API reference.
    return entitlement;
}
```

### FAQ

<AccordionGroup>
  <Accordion title="Which request parameters should I set?">
    The only parameter is the entitlement ID, passed in the path of the request URL.
  </Accordion>

  <Accordion title="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:

    ```text theme={null}
    {
        "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": "https://www.example.com/notification",
        "extensionData": {
            "price": "9.99",
            "currencyIso3": "GBP",
            "channelType": "WEB_PROMOTION",
            "channelSource": "https://bango.com/promo"
            "campaignKey": "SUMMER_PROMO",
            "referrer": "SEARCH_ENGINE"
        }
    }
    ```

    See [Bango Resale / For resellers / Reseller API reference / Reseller API reference overview](/legacy/resale/reseller/api-ref/index) for detailed information on all responses.
  </Accordion>
</AccordionGroup>