Reactivating an entitlement

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. You can cancel an entitlement to stop the user accessing the service at the end of the period for which they have already paid. To restore access, where supported by the merchant and service, you reactivate the entitlement by making a POST request to the Bango Resale API supplying the entitlement ID in the path.

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 reactivation request. For example, the reactivation might require the user to visit a web page to perform a process. In this case the entitlement record returned has status PENDING, and any later change to status ACTIVE is POSTed to the entitlement's notificationUrl, if specified.

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 reactivate_entitlement (entitlement_id) {
    // *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;

    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/reactivate/" + entitlement_id,
            headers: {
                "Authorization": get_authorization_header(),
            },
        }).from_json();

        // The responseCode tells us the result.
        switch (response.responseCode) {
            // Success: entitlement is reactivated 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
                        // reactivation asynchronously.
                        redirect_device_to({
                            url: response.parameters.url,
                        });
                        // entitlement is currently 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 reactivate this entitlement
            case "NOT_FOUND": // Invalid entitlement ID
            case "ALREADY_EXISTS": // Entitlement is already ACTIVE
            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 reactivated.
    // if reactivated, will have an entitlementId, status, and other properties:
    // see API reference.
    return entitlement;
}