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

# Configure offer plans

> Configure plans and billing for your offers.

## Overview

The plan is the engine behind every Offer. It controls when the Offer lifecycle begins, how the consumer is billed, and how the subscription progresses over time.

This page explains each component of a plan and how they combine to produce the billing behavior you want. If you haven't yet decided which plan type to use, start with [Plan Types](/offer-management/offer-plan-types).

<Tip>
  [Billing & Charging](/billing-and-charging/billing-overview) is an optional DVM capability.

  When it is enabled, the DVM uses the Offer's Plan configuration to fully automate the charging for all  end-consumers provisioned with your Offer.
</Tip>

***

## Plan components

A plan is made up of four building blocks:

<CardGroup cols={2}>
  <Card title="Lifecycle start trigger" icon="circle-play">
    Defines when the plan clock starts — and therefore when billing begins.
  </Card>

  <Card title="Currency" icon="coins">
    The currency used for all charge amounts in this plan.
  </Card>

  <Card title="Initial fee" icon="arrow-right-to-arc">
    An optional one-time charge collected at the start of the plan, before any recurring billing begins.
  </Card>

  <Card title="Phases" icon="layer-group">
    One or more periods that define pricing, duration, and renewal frequency across the Offer lifecycle.
  </Card>
</CardGroup>

***

## Lifecycle start trigger

The start trigger defines the moment the plan lifecycle begins. Every charge schedule, phase duration, and renewal is calculated from this point.

| Trigger event | When it fires | Typical use case |
| - | - | - |
| `CONSUMER_OFFER_FULLY_CREATED` | As soon as the Consumer Offer is created | Billing starts immediately at purchase — suitable for most subscription and free trial Offers |
| `CONSUMER_OFFER_FULLY_ACTIVATED` | When all entitlements in the Offer have been fully activated by the consumer | Billing starts only after the consumer has set up access — suitable for Offers where activation is a distinct consumer step |

<Info>
  For most Subscription and Free Trial Offers, `CONSUMER_OFFER_FULLY_CREATED` is the right choice. Use `CONSUMER_OFFER_FULLY_ACTIVATED` when the consumer must take an explicit action to activate their product before billing should begin.
</Info>

***

## Currency

All charge amounts in a plan are denominated in a single currency, specified using an ISO 4217 3-letter code (e.g. `USD`, `GBP`, `EUR`). The currency applies across all phases and the initial fee.

***

## Initial fee

An initial fee is an optional one-time charge collected at the start of the plan — before any phase-based recurring billing begins. It is useful for setup fees, activation charges, or one-off payments that sit outside the regular billing schedule.

<Note>
  The initial fee is a one-time charge and does not repeat. If you want a recurring charge, configure it as a phase.
</Note>

***

## Phases

A phase is a defined period of the Offer lifecycle with its own pricing, duration, and renewal frequency. Every plan must have at least one phase (except Transactional plans, which use an initial fee only).

Each phase is configured with the following fields:

### Sequence

Phases are ordered by `sequence`, starting at `0`. The DVM™ progresses through phases in sequence order — when one phase ends, the next begins automatically.

### Price type

Indicates the commercial nature of this phase. Used for analytics and reporting.

| Value | Description |
| - | - |
| `FREE` | No charge during this phase — used for free trials |
| `DISCOUNT` | Reduced price — used for introductory or promotional pricing |
| `FULL_PRICE` | Standard recurring price |

### Duration

How long the consumer stays in this phase, in ISO 8601 duration format.

| Code | Duration |
| - | - |
| `P7D` | 7 days |
| `P1M` | 1 month |
| `P3M` | 3 months |
| `P6M` | 6 months |
| `P1Y` | 1 year |

Omit `duration` on the final phase of a Subscription plan to make it evergreen — the consumer stays in this phase until the Offer is canceled.

<Warning>
  Duration must be evenly divisible by the renewal frequency. For example, a phase with `duration: P1Y` is valid with `renewalFrequency: P1M`, `P2M`, `P3M`, `P4M`, or `P6M` — but not `P5M`.
</Warning>

### Renewal frequency

How often the consumer is billed during this phase, in ISO 8601 duration format.

| Code | Billing frequency |
| - | - |
| `P7D` | Every 7 days |
| `P1M` | Every month |
| `P3M` | Every 3 months |
| `P6M` | Every 6 months |
| `P1Y` | Every year |

<Info>
  For `FREE` phases, set the renewal frequency to match the phase duration. Since no charge is issued, the value determines how the phase is tracked internally rather than when a charge fires.
</Info>

### Amount

The charge amount per renewal, expressed in minor currency units (e.g. `1299` = \$12.99 USD). Set to `0` for `FREE` phases.

### Billing description

A short description of this phase that appears on the consumer's bill. Relevant when the Billing & Charging module is enabled.

***

## How the components fit together

The table below shows how a complete plan is configured for each plan type:

| Plan type | Start trigger | Initial fee | Phases | Final phase |
| - | - | - | - | - |
| **Subscription** | Required | Optional | One or more | Evergreen — no `duration` |
| **Fixed-term** | Required | Optional | One or more | Has a `duration` — Offer ends automatically |
| **Transactional** | Required | Required | None | — |
| **Redemption** | Required | None | One evergreen `FREE` phase | Evergreen, `amount: 0` |

***

## Example plan configurations

<AccordionGroup>
  <Accordion title="Simple monthly subscription">
    A single full-price phase with no end date. The consumer is billed monthly until they cancel.

    ```json theme={null}
    "plan": {
      "lifecycleStartTrigger": {
        "triggerSource": "CONSUMER_OFFER",
        "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
      },
      "currency": "USD",
      "phases": [
        {
          "sequence": 0,
          "priceType": "FULL_PRICE",
          "renewalFrequency": "P1M",
          "amount": 1299,
          "billingDescription": "Monthly subscription"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="6-month free trial, then monthly">
    A two-phase plan. Phase 0 is free for 6 months; Phase 1 is full price recurring monthly with no end date.

    ```json theme={null}
    "plan": {
      "lifecycleStartTrigger": {
        "triggerSource": "CONSUMER_OFFER",
        "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
      },
      "currency": "USD",
      "phases": [
        {
          "sequence": 0,
          "priceType": "FREE",
          "renewalFrequency": "P1M",
          "duration": "P6M",
          "amount": 0,
          "billingDescription": "Free trial"
        },
        {
          "sequence": 1,
          "priceType": "FULL_PRICE",
          "renewalFrequency": "P1M",
          "amount": 1299,
          "billingDescription": "Monthly subscription"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="12-month fixed-term">
    A single phase with a 1-year duration. The Offer ends automatically after 12 months.

    ```json theme={null}
    "plan": {
      "lifecycleStartTrigger": {
        "triggerSource": "CONSUMER_OFFER",
        "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
      },
      "currency": "USD",
      "phases": [
        {
          "sequence": 0,
          "priceType": "FULL_PRICE",
          "renewalFrequency": "P1M",
          "duration": "P1Y",
          "amount": 999,
          "billingDescription": "12-month plan"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Redemption (free, no billing)">
    A single evergreen free phase. No charge is ever issued. Suitable for promotional grants or voucher-based access.

    ```json theme={null}
    "plan": {
      "lifecycleStartTrigger": {
        "triggerSource": "CONSUMER_OFFER",
        "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
      },
      "currency": "USD",
      "phases": [
        {
          "sequence": 0,
          "priceType": "FREE",
          "renewalFrequency": "P1M",
          "amount": 0,
          "billingDescription": "Complimentary access"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## What's next?

<Card title="Multi-phase Offers" icon="arrows-split-up-and-left" href="/offer-management/multi-phase-offers" cta="Learn about multi-phase offers" arrow="true">
  Understand how to structure Offers where a consumer's price changes after an introductory or trial period.
</Card>

<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 multi-phase plan.
</Card>

<Card title="Build an Offer" icon="pen-to-square" href="/offer-management/create-offer" cta="Build an offer" arrow="true">
  Learn the building blocks of an Offer, including products, availability, and plan setup.
</Card>