Skip to main content
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:

​
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 PENDING until the process completes. If no process is required, entitlements transition from PENDING to ACTIVE immediately.

​
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.