Configure offer plans

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.

Billing & Charging 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.

Plan components

A plan is made up of four building blocks:

Lifecycle start trigger

Defines when the plan clock starts — and therefore when billing begins.

Currency

The currency used for all charge amounts in this plan.

Initial fee

An optional one-time charge collected at the start of the plan, before any recurring billing begins.

Phases

One or more periods that define pricing, duration, and renewal frequency across the Offer lifecycle.

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

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.

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.

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

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.

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.

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

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.

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

Simple monthly subscription

A single full-price phase with no end date. The consumer is billed monthly until they cancel.

"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"
    }
  ]
}

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.

"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"
    }
  ]
}

12-month fixed-term

A single phase with a 1-year duration. The Offer ends automatically after 12 months.

"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"
    }
  ]
}

Redemption (free, no billing)

A single evergreen free phase. No charge is ever issued. Suitable for promotional grants or voucher-based access.

"plan": {
  "lifecycleStartTrigger": {
    "triggerSource": "CONSUMER_OFFER",
    "triggerEvent": "CONSUMER_OFFER_FULLY_CREATED"
  },
  "currency": "USD",
  "phases": [
    {
      "sequence": 0,
      "priceType": "FREE",
      "renewalFrequency": "P1M",
      "amount": 0,
      "billingDescription": "Complimentary access"
    }
  ]
}

What’s next?

Multi-phase Offers

Understand how to structure Offers where a consumer’s price changes after an introductory or trial period.

Free Trials

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

Build an Offer

Learn the building blocks of an Offer, including products, availability, and plan setup.

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Entitlement management

Billing & Charging

Notifications

Correlation and reconciliation

Dashboard and reporting

Partner care

Overview

Plan components

Lifecycle start trigger

Currency

Initial fee

Phases

Lifecycle start trigger

Currency

Initial fee

Phases

Sequence

Price type

Duration

Renewal frequency

Amount

Billing description

How the components fit together

Example plan configurations

What’s next?

Multi-phase Offers

Free Trials

Build an Offer

​Overview

​Plan components

Lifecycle start trigger

Currency

Initial fee

Phases

​Lifecycle start trigger

​Currency

​Initial fee

​Phases

​Sequence

​Price type

​Duration

​Renewal frequency

​Amount

​Billing description

​How the components fit together

​Example plan configurations

​What’s next?

Multi-phase Offers

Free Trials

Build an Offer

Overview

Plan components

Lifecycle start trigger

Currency

Initial fee

Phases

Sequence

Price type

Duration

Renewal frequency

Amount

Billing description

How the components fit together

Example plan configurations

What’s next?