- Bango Resale
- For resellers
- Managing entitlements
- Entitlements overview
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 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. The Bango Platform will generate this ID for you.
An entitlement always has one of these status values, describing the user's current access to the service:
| Status | Description |
|---|---|
PENDING | Waiting 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) |
ACTIVE | The user can access the service |
ACTIVE-ENDING | The user can access the service until the end of the period for which they have already paid. After then, access is denied unless they reverse the "soft ending" |
SUSPENDED | The user is temporarily unable to access the service |
CANCELLED | "Soft ending": The user had access to the service until the end of the period for which they had already paid. |
REVOKED | "Hard ending": The service is immediately withdrawn from the user |
FAILED | Communication 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 and revoke entitlements using Bango Reseller API requests (there's no delete action: use cancel or revoke). The create, update, suspend, resume, cancel and revoke 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).
You must 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:
- 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
PENDINGuntil the process completes. If no process is required, entitlements transition fromPENDINGtoACTIVEimmediately.
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.