Skip to Main Content
Get in touch

API guidelines

  2. DVM™ Overview
  3. API guidelines

The diagram below shows how the different components of the DVM™ API link together. You can see a more detailed description of each area below the diagram.

The offer catalog enables resellers to get information about the offers that have been created.

  • An offer provides product information (identifying the product, tier and content provider) enabling us to request the creation of an entitlement for each product linked to the offer.
  • An offer also contains a plan. This enables Bango to create a billing plan to manage the lifecycle of the consumer’s offer. A plan can contain one or more phases which contain information about how the consumer will be billed, e.g. a “free for 3 months transitioning to $2.99 per month” offer would have 2 phases; a free phase lasting 3 months, followed by an evergreen phase where the consumer is charged $2.99 per month.

It is not currently possible for resellers to create their own offers. Offer configuration is therefore handled by Bango alongside route onboarding.

When a consumer signs up for an offer, a reseller requests the creation of a consumer offer. This orchestrates the creation of the entitlement(s) based on the product information in the offer, and the creation of the billing plan based on the plan information in the offer.

This API will used to manage the lifecycle of the consumer’s offer. The first release will include a termination endpoint with the following supported termination types:

  • END_OF_TERM: Bango uses the plan lifecycle to calculate the most appropriate termination date for the consumer’s access to products and services linked to this consumer offer. If the consumer is in a free phase, this termination option will schedule the termination for the end of the free phase. If the consumer is in an evergreen paid phase, the termination will be scheduled for the end of the current renewal period.
    When the terminationTs is reached, Bango will send an immediate termination request to each content provider required on behalf of the reseller.
  • IMMEDIATE: A reseller can request immediate termination which stops the billing plan and entitlement access straight away. This might be used if the reseller is managing scheduling terminations directly, or in a fraud scenario. Bango immediately sends a termination request to each content provider required on behalf of the reseller.

An entitlement represents a consumer’s right to access a content provider’s product or service. This API is used by both resellers and content providers to request or share updates to a consumer’s entitlement.

State changes to entitlements are tracked by both the consumer offer API and the billing plan API. For example, if a content provider sends an immediate terminate request for an entitlement, this will also terminate the consumer offer and billing plan.

For more complex bundling (e.g. multi-party offers linking to more than one content provider), entitlement APIs should not be used directly except to request refreshed activation information.

Notifications are sent to resellers for entitlement changes and when a consumer offer is created.

For resellers using the optional Billing & Charging module, they will also receive additional notifications such as UPCOMING_PHASE_CHANGE and UPCOMING_RENEWAL which enable resellers to provide advance communication to their consumers in line with country-specific mandates for subscriptions.

General information

  • Any field marked with an asterisk in the API schema is mandatory
  • Any optional field may be omitted in the request and/or response
  • The responseMessage values that are shown are examples. There are many other strings that can be returned and these are changed and improved as the APIs evolve. They are provided to support integration and investigation as human readable information. Please do not use them for any other purpose.
  • 5xx responses are retryable. Before returning a 5xx response, Bango will have retried the request 3 times very quickly in succession before returning an error. Partners should implement their own retry process in addition to this to support their own error handling flows. A back off retry approach is recommended (e.g. using Fibonacci).
  • Each API has a change log which you can use to see what changes have been made to the API, and when. Change versioning follows the format of major.minor.fix. A major change would be considered a breaking change (e.g. to avoid breaking any existing integrations, we would create a new version of the API instead). A minor change includes both upgrades (new features) and updates (enhancements to existing features) to the API. A fix would cover mistakes/improvements to the documentation itself, or bug fixes.
  • Bango provides 2 environments for partners:
    • Sandbox
      This is our test integration environment. When integrating to Bango, partners should connect to this environment first. This environment allows you to do 2-party and 3-party testing. Entitlements created in this environment are not considered to be part of your “managed entitlement” total.
    • Production
      This is our live environment. This contains your live routes and all entitlements created here are part of your “managed entitlement” total. If there is a requirement for live-proving, this will need to be done in production, and we strongly advise that you track and terminate test entitlements during this process.
  • Not all APIs have the same base URL. Please refer to each API schema for specific details.