> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up offers with multiple phases

> Structure Offers where a consumer's price automatically transitions after an introductory, trial, or discounted period.

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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](/billing-and-charging/notifications).
</Tip>

***

## Phase configuration rules

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

<CardGroup cols={2}>
  <Card title="Sequence starts at 0" icon="list-ol">
    Phases must be numbered sequentially starting from `0`. The DVM™ processes them in order — gaps or out-of-order sequences are not supported.
  </Card>

  <Card title="Duration drives the transition" icon="clock">
    Each phase except the final one must have a `duration`. When that duration expires, the transition to the next phase fires automatically.
  </Card>

  <Card title="Final phase is evergreen or fixed" icon="infinity">
    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.
  </Card>

  <Card title="Duration must be divisible by renewal frequency" icon="calculator">
    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.
  </Card>
</CardGroup>

***

## Example configurations

<AccordionGroup>
  <Accordion title="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.

    ```json theme={null}
    "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
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    "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
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    "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
  </Accordion>
</AccordionGroup>

***

## 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

<Info>
  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.
</Info>

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

***

## What's next?

<Card title="Free Trials" icon="gift" href="/offer-catalog/free-trials" cta="Set up a free trial" arrow="true">
  Step-by-step guidance on configuring a free trial Offer using a two-phase plan.
</Card>

<Card title="Plan Configuration" icon="tag" href="/offer-catalog/plan-configuration" cta="Configure a plan" arrow="true">
  Full reference for start triggers, phases, durations, renewal frequency, and pricing.
</Card>

<Card title="Billing & Charging Notifications" icon="bell" href="/billing-and-charging/notifications" cta="View notifications" arrow="true">
  Set up advance notifications to inform consumers before their phase changes and new pricing takes effect.
</Card>