Set up offers with multiple phases

Overview

A multi-phase Offer is an Offer whose plan contains more than one phase — allowing the commercial terms to change automatically over the lifecycle of the subscription. Use multi-phase Offers when commercial terms need to change during the subscription lifecycle. The DVM automatically transitions between configured phases without manual intervention. Common examples include:

Free trial → paid subscription — the consumer gets free access for a defined period, then moves to a recurring charge
Introductory discount → full price — the consumer is charged a lower price for an initial period, then transitions to the standard rate
Discounted fixed-term → evergreen — a promotional rate runs for a set number of months, then the consumer rolls onto a standard recurring plan

In every case, the DVM™ manages the phase transition automatically — the consumer’s entitlement and access remain uninterrupted, and if Billing & Charging is enabled, the updated charge amount is applied from the start of the new phase.

How phase transitions work

Each phase in a plan has a sequence number, starting at 0. The DVM™ processes phases in sequence order. When the duration of a phase expires, the plan automatically advances to the next phase.

Phase 0 begins

The plan lifecycle starts based on the configured lifecycleStartTrigger. The consumer enters Phase 0 — the introductory or promotional phase.If Billing & Charging is enabled, the DVM™ issues charges at the price and frequency defined in Phase 0.

Phase 0 ends

When the duration of Phase 0 expires, the plan advances automatically to Phase 1. No manual action is required.If Billing & Charging is enabled, an UPCOMING_PHASE_CHANGE notification is sent in advance of the transition so you can inform the consumer before their price changes.

Phase 1 begins

The consumer moves into Phase 1. The new pricing and renewal frequency take effect from this point.If Billing & Charging is enabled, the DVM™ begins issuing charges at the Phase 1 price and frequency.

Subscription continues

For Subscription plans, the final phase is evergreen — it has no duration and continues until the Offer is canceled. For Fixed-term plans, the final phase has a duration and the Offer ends automatically when it expires.

The UPCOMING_PHASE_CHANGE notification is sent ahead of every phase transition. This gives you advance notice to communicate pricing changes to your consumers before they are charged at the new rate. See Billing & Charging Notifications.

Phase configuration rules

When configuring a multi-phase plan, keep the following in mind:

Sequence starts at 0

Phases must be numbered sequentially starting from 0. The DVM™ processes them in order — gaps or out-of-order sequences are not supported.

Duration drives the transition

Each phase except the final one must have a duration. When that duration expires, the transition to the next phase fires automatically.

Final phase is evergreen or fixed

For Subscription plans, omit duration on the last phase to make it evergreen. For Fixed-term plans, include a duration on the last phase so the Offer ends automatically.

Duration must be divisible by renewal frequency

The phase duration must divide evenly into the renewalFrequency. For example, a 6-month phase (P6M) with monthly billing (P1M) is valid. A 6-month phase with a 4-month renewal (P4M) is not.

Example configurations

3-month introductory discount, then full price monthly

Phase 0 runs for 3 months at a discounted price. Phase 1 is the full-price evergreen subscription.

"plan": {
  "lifecycleStartTrigger": {
    "triggerSource": "CONSUMER_OFFER",
    "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
  },
  "currency": "USD",
  "phases": [
    {
      "sequence": 0,
      "priceType": "DISCOUNT",
      "renewalFrequency": "P1M",
      "duration": "P3M",
      "amount": 499,
      "billingDescription": "Introductory offer"
    },
    {
      "sequence": 1,
      "priceType": "FULL_PRICE",
      "renewalFrequency": "P1M",
      "amount": 1299,
      "billingDescription": "Monthly subscription"
    }
  ]
}

What the consumer experiences:

Months 1–3: charged at the discounted rate
Month 4 onwards: charged at the full price monthly
Before Month 4: receives an UPCOMING_PHASE_CHANGE notification

6-month free trial, then monthly at full price

Phase 0 is free for 6 months. Phase 1 is a full-price evergreen monthly subscription.

"plan": {
  "lifecycleStartTrigger": {
    "triggerSource": "CONSUMER_OFFER",
    "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
  },
  "currency": "GBP",
  "phases": [
    {
      "sequence": 0,
      "priceType": "FREE",
      "renewalFrequency": "P1M",
      "duration": "P6M",
      "amount": 0,
      "billingDescription": "Free trial"
    },
    {
      "sequence": 1,
      "priceType": "FULL_PRICE",
      "renewalFrequency": "P1M",
      "amount": 999,
      "billingDescription": "Monthly subscription"
    }
  ]
}

What the consumer experiences:

Months 1–6: no charge
Month 7 onwards: charged monthly at full price
Before Month 7: receives an UPCOMING_PHASE_CHANGE notification

3-month discounted fixed-term, then 9-month full price (12-month total)

A two-phase fixed-term plan. Phase 0 is discounted for 3 months. Phase 1 is full price for 9 months. The Offer ends automatically after 12 months.

"plan": {
  "lifecycleStartTrigger": {
    "triggerSource": "CONSUMER_OFFER",
    "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
  },
  "currency": "EUR",
  "phases": [
    {
      "sequence": 0,
      "priceType": "DISCOUNT",
      "renewalFrequency": "P1M",
      "duration": "P3M",
      "amount": 299,
      "billingDescription": "Promotional rate"
    },
    {
      "sequence": 1,
      "priceType": "FULL_PRICE",
      "renewalFrequency": "P1M",
      "duration": "P9M",
      "amount": 999,
      "billingDescription": "Standard subscription"
    }
  ]
}

What the consumer experiences:

Months 1–3: charged at the promotional rate
Months 4–12: charged at the full price monthly
Offer closes automatically after month 12

Configuring different ProductKey’s per Phase

The DVM™ supports the ability to configure a different productKey for each phase of a multi-phase plan. This means that when a consumer’s subscription transitions between phases — for example from a promotional period to full price — the entitlement productKey associated with that consumer can automatically update to reflect the new phase.

Why this matters

The productKey is used by the Reseller’s or Content Provider’s connected systems to identify which product configuration a consumer holds. In a multi-phase Offer, the promotional and paid phases may represent meaningfully different states — different billing logic, reporting categories, or product configurations on the Content Provider side. Without this capability, the productKey remains fixed for the entire subscription lifecycle, even as the Offer changes phase. This creates a gap when downstream systems need to distinguish between a consumer on a promotional rate versus a full-price subscription. With ProductKey change on phase change, the DVM™ automatically updates the productKey on the entitlement at the point of transition — ensuring the correct product configuration is always applied, and that promotional and paid phases are clearly identifiable across connected systems.

Example

A Reseller launches a 2-month promotional Offer for a music service. The product has a Basic tier, and the Reseller has two productKey values configured — one for the promotional phase and one for the paid phase:

Phase	Phase type	productKey
Phase 0	`DISCOUNT` (2 months)	`Bango_Basic_Promo`
Phase 1	`FULL_PRICE` (evergreen)	`Bango_Basic`

When the consumer’s subscription transitions from Phase 0 to Phase 1, the DVM™ automatically updates their entitlement productKey from Bango_Basic_Promo to Bango_Basic. No manual intervention is required. The same applies to upgrade and downgrade tiers. If the Offer also includes Standard and Premium tiers, each tier can have its own productKey per phase:

Tier	Phase 0 productKey	Phase 1 productKey
Basic	`Bango_Basic_Promo`	`Bango_Basic`
Standard	`Bango_Standard_Promo`	`Bango_Standard`
Premium	`Bango_Premium_Promo`	`Bango_Premium`

Scope and availability

ProductKey change on phase change is configured at onboarding. productKey mappings per phase are defined during the initial Offer setup — contact your Bango integration team to enable this for your Offers.

This capability currently supports single-tier products. Multi-tier and dynamically configured productKey mappings will be available in a future release.

What’s next?

Free Trials

Step-by-step guidance on configuring a free trial Offer using a two-phase plan.

Plan Configuration

Full reference for start triggers, phases, durations, renewal frequency, and pricing.

Billing & Charging Notifications

Set up advance notifications to inform consumers before their phase changes and new pricing takes effect.

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Entitlement management

Billing & Charging

Notifications

Correlation and reconciliation

Dashboard and reporting

Partner care

Overview

How phase transitions work

Phase configuration rules

Sequence starts at 0

Duration drives the transition

Final phase is evergreen or fixed

Duration must be divisible by renewal frequency

Example configurations

Configuring different ProductKey’s per Phase

Why this matters

Example

Scope and availability

What’s next?

Free Trials

Plan Configuration

Billing & Charging Notifications

​Overview

​How phase transitions work

​Phase configuration rules

Sequence starts at 0

Duration drives the transition

Final phase is evergreen or fixed

Duration must be divisible by renewal frequency

​Example configurations

​Configuring different ProductKey’s per Phase

​Why this matters

​Example

​Scope and availability

​What’s next?

Free Trials

Plan Configuration

Billing & Charging Notifications

Overview

How phase transitions work

Phase configuration rules

Example configurations

Configuring different ProductKey’s per Phase

Why this matters

Example

Scope and availability

What’s next?