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
  2. For resellers
  3. Managing entitlements
  4. Updating an entitlement

Updating an entitlement

Making sparse updates to an existing entitlement

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. To make changes to an existing entitlement, you send a PATCH request to the Bango Resale API.

You can't cancel, or revoke entitlements using PATCH requests: a PATCH can't change the status property to CANCELLED or REVOKED. Use the more specific cancel, revoke, API requests instead.

As part of the API request, you supply:

You can suspend, or resume entitlements using PATCH requests. For more information see suspend, resume, API requests instead.

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 2xx responses, the entitlement record.

Depending on merchant requirements and potentially other factors, the response code might indicate that your code needs to take some action as a result of the update request. For example, the update might require the user to visit a web page to perform a process. In this case the entitlement record returned contains your requested updates but with status PENDING, and any later change to status ACTIVE is POSTed to the entitlement's notificationUrl, if specified.

Sequence diagrams
Update with no further action required

The Bango Platform updates the entitlement and the user does not have to perform a process. The entitlement status does not change.

Update with required user process

The merchant requires the user to perform a process. The Bango Platform returns an updated 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.

Failed request to update entitlement

The Bango Platform can't update the entitlement, and returns the reason in the response to the API request.

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.

function update_entitlement (entitlement_id, properties_to_update = {}) {
    // *Always* use this endpoint prefix for the Bango Resale API.
    const base_url = "https://resale.api.bango.net";

    // This is what's returned with HTTP 2xx.
    let entitlement = null;

    // The entitlement ID is passed in the body not the path.
    // Here, assume properties_to_update is a map of entitlement
    // property names to values.
    // See API ref for details of which properties you can update.
    const request_body_params = properties_to_update
        .copy()
        .set('entitlementId', entitlement_id);

    try {
        // PATCH UTF-8 JSON to the Bango Resale API and parse the JSON response
        let response = rest_client_call({
            method: "PATCH",
            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: no action required
            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.
                        // Set entitlement's notificationUrl to
                        // receive notification of entitlement
                        // changes asynchronously.
                        redirect_device_to({
                            url: response.parameters.url,
                        });
                        // Updated entitlement is returned in this case
                        // but with status 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 update this entitlement
            case "NOT_FOUND": // Invalid entitlement ID
            case "TOO_MANY_REQUESTS": // Request limit reached: try again later
                throw "Unable to update 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 updated.
    // if updated, will have an entitlementId, status, and other properties:
    // see API reference.
    return entitlement;
}
FAQ
Which request parameters should I set?

You must set the entitlementId. Include any other parameters you want to update: any parameter not included in the request is not changed.

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

Why might I have to send the user to a web page?

It depends on the merchant, the user, the service, and possibly other factors. In most cases you won't have to do anything: the update request will return the response code OK.

One likely reason for the response code CLIENT_ACTION_REQUIRED may be a change in productKey: perhaps you're upgrading the user to a new service tier, and the merchant requires an additional setup process.

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 for detailed information on all responses.

Copyright © 2000–2021 Bango.net Limited