Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
Bango Developer
  1. Bango Resale
  2. For resellers
  3. Managing entitlements
  4. 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:

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
ACTIVE-ENDINGThe 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"
SUSPENDEDThe 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
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 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:

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.

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–2022 Limited