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

Subscription lifecycle and timeline

States, events, and phase transitions

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:

State Description

State	Description
`PENDING`	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`.

PENDING

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:

A Trial phase, duration three months, at zero cost
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:

Date	Event	State	Phase	Payment
Sep 1, 2020	Alice creates subscription	`ACTIVE`	Trial	None
Dec 1, 2020	Phase change + billing	`ACTIVE`	Evergreen	USD 5.99
Jan 1, 2021	Billing	`ACTIVE`	Evergreen	USD 5.99
Feb 1, 2021	Billing	`ACTIVE`	Evergreen	USD 5.99
Feb 14, 2021	Alice decides to cancel	`ACTIVE`	Evergreen	None
March 1, 2021	Subscription ends	`CANCELLED`	Evergreen	None

← Previous: Products and plans Next: Billing periods →

In this section: