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

# Creating an entitlement

> Asking a merchant to activate a service for a user

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. To request service access for a user, you create an entitlement by making a `POST` request to the Bango Resale API.

As part of the API request, you supply:

* The unique, persistent identifer for the user. This is an ID you maintain: the Bango Platform treats it as opaque.
* Merchant and product identifiers, and (depending on the merchant) an offer identifier, which together identify the service you want to activate for the user. Bango maintains these identifiers, and ensures you can only create entitlements for authorized services.
* A notification URL. The Bango Platform POSTs asynchronous entitlement updates to this URL. See [Bango Resale / For resellers / Reseller API reference / Notifications from Bango](/legacy/resale/reseller/api-ref/notifications).
* Optionally, other parameters including custom data. See [Bango Resale / For resellers / Reseller API reference / Reseller API reference overview](/legacy/resale/reseller/api-ref/index).

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.

For some services, the status of the new entitlement is `ACTIVE` and the user can access the service immediately. For others, the status is `PENDING`, which means the merchant won't activate the service until a process is complete. This process might include actions by the user: for example, registering for the service. In this case the response code indicates what your code should do (for example, send the user to a web page), and the response contains any extra data required (for example, a registration URL).

### Sequence diagrams

<AccordionGroup>
  <Accordion title="Immediate service activation">
    The Bango Platform activates the service for the user immediately, returning an entitlement with status `ACTIVE`.

    <Frame>
      <img src="https://mintcdn.com/bango/wsCONCkeI5LcokDc/images/image-33.png?fit=max&auto=format&n=wsCONCkeI5LcokDc&q=85&s=65e8dd18194d8803108a65f538ad751d" alt="Image" width="561" height="350" data-path="images/image-33.png" />
    </Frame>
  </Accordion>

  <Accordion title="Service activation after user completes merchant process">
    The merchant requires the user to perform a process such as registration. The Bango Platform returns an entitlement with status `PENDING`, with the response code `CLIENT_ACTION_REQUIRED` and action `NAVIGATE_TO_URL`, together with the target URL. You send the user to the URL, and when the user completes the process the Bango Platform notifies you by direct server-to-server communication.

    <Frame>
      <img src="https://mintcdn.com/bango/wsCONCkeI5LcokDc/images/image-33.png?fit=max&auto=format&n=wsCONCkeI5LcokDc&q=85&s=65e8dd18194d8803108a65f538ad751d" alt="Image" width="561" height="350" data-path="images/image-33.png" />
    </Frame>
  </Accordion>

  <Accordion title="Failed request for service activation">
    The Bango Platform can't activate the service for the user, and returns the reason in the response to the API request.

    <Frame>
      <img src="https://mintcdn.com/bango/wsCONCkeI5LcokDc/images/image-33.png?fit=max&auto=format&n=wsCONCkeI5LcokDc&q=85&s=65e8dd18194d8803108a65f538ad751d" alt="Image" width="561" height="350" data-path="images/image-33.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.

Some functions referenced in the skeleton code, such as `redirect_device_to`, are not defined. You need to implement these where possible.

```text theme={null}
function create_entitlement (user_id, merchant, product, offer = null, notification_url) {
    // *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;

    const request_body_params = {
        // Your unique identifier for the user.
        customerIdentifier: user_id,

        // Identifier for the merchant providing the service,
        // supplied by Bango.
        merchantAccountKey: merchant,

        // Identifier for the product representing the service,
        // supplied by Bango.
        productKey: product,

        // Identifier for the offer associated with the service,
        // supplied by Bango. (Use null, or omit, if no offer key applies)
        offerKey: offer,

        // Your custom URL: the Bango Platform POSTs asynchronously
        // to this URL on changes to the entitlement.
        notificationUrl: notification_url,

        // See API reference for more parameters.
        // You could use your own entitlement IDs if you want, for example:
        // entitlementId: get_entitlement_id(...);
    };

    try {
        // POST UTF-8 JSON to the Bango Resale API and parse the JSON response
        let response = rest_client_call({
            method: "POST",
            url: base_url + "entitlement",
            headers: {
                "Authorization": get_authorization_header(),
                "Content-Type": "application/json",
            },
            body: make_json_string(request_body_params),
        }).from_json();

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

            // More to do: The reseller must take action
            case "CLIENT_ACTION_REQUIRED":
                // This response parameter tells us what we need to do.
                switch (response.parameters.action) {
                    case "NAVIGATE_TO_URL":
                        // Send the user to a particular web page
                        // to complete a merchant-defined process.
                        // request_body_params must include notificationUrl
                        // to ensure you receive notification of service
                        // activation asynchronously.
                        redirect_device_to({
                            url: response.parameters.url,
                        });
                        // entitlement is created and PENDING
                        entitlement = response;
                        break;

                    default:
                        // Unrecognized action.
                        // Check the documentation again.
                        throw "Unrecognized client action";
                }

                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_AVAILABLE": // Unable to activate this service
            case "ALREADY_EXISTS": // You tried to reuse an entitlement ID
            case "TOO_MANY_REQUESTS": // Request limit reached: try again later
                throw "Unable to create 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 created.
    // If created, will have an entitlementId, status, and other properties:
    // see API reference.
    return entitlement;
}
```

### FAQ

<AccordionGroup>
  <Accordion title="Which request parameters should I set?">
    You must set the `customerIdentifier`, `merchantAccountKey`, and `productKey` parameters, to identify the merchant service and the user.

    Some merchants may also require you to set the `offerKey` parameter.

    Bango recommends you set the `notificationUrl` to receive [asynchronous notifications](/legacy/resale/reseller/api-ref/notifications) from the Bango Platform.

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

  <Accordion title="What value should I use for customerIdentifier?">
    Use your own system's unique identifier for the user. The Bango Platform treats this as an opaque string.
  </Accordion>

  <Accordion title="What values should I use for merchantAccountKey, productKey, and offerKey?">
    The `merchantAccountKey` and `productKey` parameters, and (depending on the merchant) the `offerKey` parameter, together identify the service you want to allow the user to access.

    Bango maintains the allowed values for these keys. When you have an agreement with a merchant to resell a service, Bango will let you know which values to use. The Bango Platform ensures you can only create entitlements for authorized services.

    For testing, use special values for these keys. See [Bango Resale / For resellers / Testing](/legacy/resale/reseller/testing).
  </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 this code to determine how to react. For each distinct `responseCode`, the response might include other useful values.

    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>