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 can use your own IDs, or let the Bango Platform generate IDs for you. Every entitlement must have an ID unique to you (not necessarily globally unique).
An entitlement always has one of these status values, describing the user's current access to the service:
|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)|
|The user can access the service|
|The user is temporarily unable to access the service|
|"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|
|"Hard ending": The service is immediately withdrawn from the user|
|The merchant reported that the activation failed (some merchants may let you try to reactivate the entitlement)|
|The merchant reported that the user failed to complete the service activation process in time (some merchants may let you try to reactivate the entitlement)|
|The merchant reported that the user is already subscribed to the service (some merchants may let you try to reactivate the entitlement)|
|The merchant rejected the activation for an unspecified reason (some merchants may let you try to reactivate the entitlement)|
|Communication with the merchant failed, and the Bango Platform is unsure of the user's ability to access the service|
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:
PENDINGuntil the process completes. If no process is required, entitlements transition from
PENDINGstate if the merchant requires the user to complete a process.
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.