Digital Vending Machine® Lifecycle Management – Subscriptions
DVM > Lifecycle Management > Subscriptions
Subscriptions
Products, Plans & Phases
Bango Subscriptions terminology
- The product is the physical or virtual item or service the user wants. For example, a streaming music service, a stock tips email, or a physical gaming console.
- The plan defines the terms on which the user has access to the product. Each plan is built with one or more phases. For example, “one month free then the full price paid monthly”, or “a discounted price paid annually”, or “one month free then three months discounted then the full price paid monthly”, or “one week only at a fixed price”.
- The phase defines individual periods of time that collectively creates a plan. For example, “one month free” is defined as a phase which automatically rolls onto a “full price” phase within one plan.
When creating your product catalog you must specify at least one product, which must have at least one plan under it and every plan needs at least one phase.
How to construct your product catalog with Bango.
Scenario – Music streaming service with three different user offers.
| Plan Number | Plan Name | Plan Description |
|---|---|---|
| 1 | 6 months on us | The partner wants to offer their users access to the music streaming service for 6 months at no cost. Following the six months of no cost, the partner wants the user to be charged $10 per month with no automatic expiry. |
| 2 | 3 months on us then 3 months half price | The partner wants to offer their users access to the music streaming service for 3 months at no cost to the user. Following the three months of no cost, the partner wants the user to be charged half the full retail price at $5 then automatically rollover to be charged $10 per month from then on with no automatic expiry. |
| 3 | Full retail price | The partner wants to offer their users access to the music streaming service at full retail price with no automatic expiry. |
Above plan configurations:
- Phase 1:
- Phase Type – DISCOUNT
- Phase Period – MONTHS
- Phase Length – 6
- Billing Period – NO_BILLING_PERIOD
- Price – 0.00
- Currency – USD
- Phase 2
- Phase Type – EVERGREEN
- Phase Period – UNLIMITED
- Phase Length – N/A
- Billing Period – MONTHLY
- Price – 10.00
- Currency – USD
- Phase 1:
- Phase Type – DISCOUNT
- Phase Period – MONTHS
- Phase Length – 3
- Billing Period – NO_BILLING_PERIOD
- Price – 0
- Currency – USD
- Phase 2:
- Phase Type – DISCOUNT
- Phase Period – MONTHS
- Phase Length – 3
- Billing Period – MONTHLY
- Price – 5.00
- Currency – USD
- Phase 4
- Phase Type – EVERGREEN
- Phase Period – UNLIMITED
- Phase Length – N/A
- Billing Period – MONTHLY
- Price – 10.00
- Currency – USD
Phase 1:
- Phase Type – EVERGREEN
- Phase Period – UNLIMITED
- Phase Length – N/A
- Billing Period – MONTHLY
- Price – 10.00
- Currency – USD
States, Events & Phase transitions
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 |
|---|---|
| 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. |
Billing Periods
In the product catalog, each product has a number of plans, each with at least one phase. A phase defines a period of time, a price, and a billing period.
The billing period controls when the Bango Subscriptions API takes payments from the user while that phase is active. The periods start from the start date of that phase.
The table shows the available billing periods. The final column shows the next payment date for each billing period, given a phase start date of September 1, 2020.
| Billing period | Description | After 2023-09-01 |
|---|---|---|
| MONTHLY | Every month on the same day | 2023-10-01 |
| DAILY | Every day | 2023-09-02 |
| WEEKLY | Every 7 days | 2023-09-08 |
| BIWEEKLY | Every 2 weeks | 2023-09-15 |
| THIRTY_DAYS | Every 30 days | 2023-10-01 |
| SIXTY_DAYS | Every 60 days | 2023-10-31 |
| NINETY_DAYS | Every 90 days | 2023-11-30 |
| QUARTERLY | Every 3 months on the same day | 2023-12-01 |
| BIANNUAL | Every 6 months on the same day | 2024-03-01 |
| ANNUAL | Every year on the same day of the same month | 2024-09-01 |
Payments are taken no earlier than 00:00 UTC on the payment date. The precise time is derived from the time the subscription was created.
Subscription notifications
Please click here to see all supported types of Subscriptions notifications.