Resuming an entitlement

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. You can temporarily withdraw a user's access to that service by suspending the entitlement. To restore that access, where supported by the merchant and service, you resume the entitlement by making a PATCH request to the Bango Resale API with entitlementBenefits set to NORMAL.

As part of the API request, you supply:

• The entitlement ID
• The entitlement benefits enum

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. The record includes any additional custom data as part of the entitlement's extensionData property. The record status is ACTIVE, and the dateResumed property marks the date and time of the resume request.
• For HTTP 202 responses, the entitlement record. The record includes any additional custom data as part of the entitlement's extensionData property. The record status is SUSPENDED. HTTP 202 responses indicates that the merchant has accepted your request and has queued it for processing within their system. You should expect to receive a notification from Bango when the merchant has completed the processing of the queued 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 are not defined. You need to implement these where possible.

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

    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);
        .set('entitlementBenefits', "NORMAL");

    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;
}

{
    "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-06-28T14:15:03Z",
    "dateActivated": "2017-06-28T14:30:05Z",
    "dateExpiry": null,
    "dateEnded": null,
    "dateSuspended": "2017-06-29T07:58:36Z",
    "dateResumed": "2017-07-29T12:13:14Z",
    "extensionData": {}
}

{
    "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": "SUSPENDED",
    "dateCreated": "2017-06-28T14:15:03Z",
    "dateActivated": "2017-06-28T14:30:05Z",
    "dateExpiry": null,
    "dateEnded": null,
    "dateSuspended": "2017-06-29T07:58:36Z",
    "dateResumed": null
    "extensionData": {}
}