Skip to main content
In the Bango Subscriptions API:
  • A product is the physical or virtual item or service the user receives as part of the subscription, and is made available for subscription under one or more plans
  • A plan defines the terms on which the user has access to the product, as an ordered list of phases
  • A phase defines a period of time, a price, and a billing period
As time passes, a subscription to a product under a plan passes through each of the plan’s phases in turn. The subscription might eventually end (for example, by user cancellation) or might continue indefinitely. In addition, each subscription has a state value. The state is always one of: The user does not yet have access to the product or service associated with the subscription. Subscriptions start in PENDING state if you set entitlementStartDate to a future date when creating them. PENDING subscriptions automatically transition to ACTIVE state on that date. | | ACTIVE | The user has access to the product or service associated with the subscription. Subscriptions start in ACTIVE state if you set entitlementStartDate to the current date or a past date when creating them. | | CANCELLED | The user no longer has access to the product or service associated with the subscription. Subscriptions transition from ACTIVE to CANCELLED state when a user cancellation becomes effective. The Bango Subscriptions API allows for immediate cancellation (access stops instantly) or scheduled cancellation (access stops at a future date). The subscription changes to CANCELLED when access stops, not when the cancellation API request is made. To identify whether a subscription is scheduled for cancellation, check its cancelledDate property. If not null, it is the UTC YYYY-MM-DD date when cancellation becomes effective. Subscriptions with a scheduled cancellation date can be “uncanceled”: the cancelledDate is set to null and the subscription state won’t change to CANCELLED. |

​
Example: free trial

Let’s look at an example plan and see what happens over time. The product catalog contains the product “Bango Music”, with a full price of USD 5.99 per month, and one of its plans is “Free trial – three months”. The phases would be:
  1. A Trial phase, duration three months, at zero cost
  2. An Evergreen phase, of unlimited duration, at price USD 5.99, billed monthly in advance
On September 1, 2020, Alice creates a subscription to the Bango Music service under the “Free trial – three months” plan. The service is made available to her immediately. In mid February 2021 she decides to cancel the plan, and the customer portal she uses ensures she continues to have access to the service until the next payment point. Here’s the complete timeline: