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. Managing entitlements

Entitlements overview

About entitlements and the entitlement lifecycle

Entitlements record a user's rights to access a service provided by a merchant. You create, update, suspend, resume, cancel, reactivate, and revoke entitlements to control access.

In the Bango Platform, an entitlement is a record describing the merchant, the merchant's service, the user (customer), the current status of the entitlement, some timestamp metadata, and any custom data you want to associate with the entitlement.

Every entitlement has a string ID. You should let the Bango Platform generate IDs for you.

An entitlement always has one of these status values, describing the user's current access to the service:

StatusDescription
PENDINGWaiting for the user to complete a required process before service activation or update (usually registering for the service: each merchant may be different, and some may not require a process – in which case you never see this status)
ACTIVEThe user can access the service
SUSPENDEDThe user is temporarily unable to access the service
CANCELLED"Soft ending": The user can access the service until the end of the period for which they have already paid. After then, access is denied
REVOKED"Hard ending": The service is immediately withdrawn from the user
ACTIVATION_FAILEDThe merchant reported that the activation failed (some merchants may let you try to reactivate the entitlement)
ACTIVATION_EXPIREDThe merchant reported that the user failed to complete the service activation process in time (some merchants may let you try to reactivate the entitlement)
ACTIVATION_ALREADY_ACTIVEThe merchant reported that the user is already subscribed to the service (some merchants may let you try to reactivate the entitlement)
ACTIVATION_REJECTEDThe merchant rejected the activation for an unspecified reason (some merchants may let you try to reactivate the entitlement)
FAILEDCommunication with the merchant failed, and the Bango Platform is unsure of the user's ability to access the service

Actions and changes to status values

You can create, read, update, suspend, resume, cancel, revoke, and reactivate entitlements using Bango Resale API requests (there's no delete action: use cancel or revoke). The create, update, suspend, resume, cancel, revoke, and reactivate actions may change the entitlement's status, if the merchant supplying the service supports that action. The status may also change at any time as the result of a merchant action (for example, a merchant may detect fraud and revoke the entitlement).

Bango recommends you specify a notification URL when you create an entitlement: the Bango Platform POSTs asynchronous entitlement updates to this URL.

This hierarchical state chart shows how the status value changes:

State chart

  • The Lifecycle substate, shown in yellow, contains the interesting parts.
  • Some merchants require users to complete a process before service activation. In this case, the entitlement is PENDING until the process completes. If no process is required, entitlements transition from PENDING to ACTIVE immediately.
  • Reactivating an entitlement, or making updates in some cases (depending on the merchant, service, and potentially other factors), may transition to the PENDING state if the merchant requires the user to complete a process.
  • Some merchants may not support all actions for a service. For example, some merchants may not let you reactivate a canceled entitlement, or suspend and resume entitlements.

Idempotency: detecting and rejecting unwanted duplicate requests

The Bango Platform supports idempotency in the Bango Resale API. With idempotency, the Bango Platform guarantees to return the same response given a duplicate request. For example, if a store makes an API request to create an entitlement, and then makes the same API request again, the response to the second request will be identical to the response to the first request: the second request does not create a new entitlement.

To use idempotency, include the HTTP header X-RequestIdentifier with a request. The value should be a unique identifier for the request. This header lets the Bango Platform identify repeated requests.

Copyright © 2000–2019 Bango.net Limited