Create a subscription plan

Create a new subscription plan with one or more pricing variations.

A subscription plan defines the billing structure for subscriptions. Each plan can have multiple variations (e.g., monthly vs. yearly), and each variation can have multiple billing phases (e.g., trial period followed by regular billing).

How subscription plans work​

A subscription plan consists of three hierarchical levels:

  1. Plan: The top-level container with a name (e.g., "Pro Plan")
  2. Variations: Different pricing options within the same plan (e.g., monthly vs. yearly)
  3. Phases: Sequential billing stages within each variation (e.g., trial → regular billing)

Understanding phases​

Phases execute in sequence based on their ordinal value (1, 2, 3, etc.):

  • Each phase has a cycle_duration (e.g., P1M for monthly)
  • Each phase has a cycle_count that determines how many cycles before moving to the next phase
  • If cycle_count is null or omitted, the phase continues indefinitely
  • When a phase completes its cycles, the subscription moves to the phase with the next ordinal
  • If the last phase completes its cycles and no next phase exists, the subscription is automatically stopped
Example

A plan with a 7-day trial followed by monthly billing:

  • Phase 1 (ordinal=1): cycle_duration=P7D, cycle_count=1, amount=0
  • Phase 2 (ordinal=2): cycle_duration=P1M, cycle_count=null, amount=9900

After 1 week (1 cycle), the subscription moves from phase 1 to phase 2 and bills monthly indefinitely.

Request​

Header parameters
Header parameters

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

Info

For more information, see: Authentication

Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16]
Example: "2025-10-16"

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

Info

For more information about API versioning, see: API versions.

Request body
Body object

Possible length: non-empty and <= 1024 characters

The name of the subscription plan.

Possible number of items: non-empty

List of subscription plan variations (e.g., monthly, yearly pricing options).

Possible number of items: non-empty

List of billing phases for this variation.

Possible values: >= 1

The sequential order of this phase in the subscription billing lifecycle.

Phases execute in ascending order based on this value:

  • Phase with ordinal=1 executes first
  • Phase with ordinal=2 executes second, and so on

When a phase completes its cycle_count, the subscription automatically progresses to the phase with the next ordinal value.

Example: A subscription with phases ordered as ordinal=1 (trial), ordinal=2 (regular), ordinal=3 (discounted) will progress through them in that sequence.

The length of each billing cycle for this phase in ISO 8601 duration format.

This determines how often the customer is billed during this phase. The total time spent in a phase is cycle_duration × cycle_count.

Common durations:

DurationDescription
P1M1 month
P1Y1 year
P15D15 days
P1W1 week
PT2H2 hours

Example: If cycle_duration=P1M and cycle_count=12, the customer will be billed monthly for 12 months (1 year total).

Possible values: >= 1

Number of billing cycles for this phase before moving to the next phase.

ValueBehavior
null or omittedPhase continues indefinitely. The subscription remains in this phase with no automatic progression.
Specific number (e.g., 1, 3, 12)After completing this many billing cycles, the subscription automatically moves to the next phase as determined by the ordinal field.

Example: If cycle_count=3 and cycle_duration=P1M, the subscription will complete 3 monthly cycles then move to the phase with the next highest ordinal value.

Note

If no next phase exists in after a cycle with a specific cycle_count, the subscription will automatically stop when it completes its cycles.

Subscription amount in minor currency units (e.g., cents for USD, pence for GBP).

For example, 9900 in GBP represents £99.00.

Info

Conversion between major and minor units varies by currency. For instance, 100 minor units equal £1.00 in GBP, whereas in ISK they represent 100 units. For more details, see the ISO 4217 standard.

Possible length: >= 3 characters and <= 3 characters

ISO 4217 currency code in upper case.

Info

For more information about the supported currencies, see: Help Center.

Response​

Subscription plan created successfully

Response body
Body object

Unique identifier for the subscription plan.

Possible length: non-empty and <= 1024 characters

The name of the subscription plan.

Possible values: [active, deactivated]

The state of the subscription plan.

StateDescription
activeThe plan is active and can be used to create new subscriptions.
deactivatedThe plan has been deactivated and cannot be used for new subscriptions.

The date and time the subscription plan was created in ISO 8601 format.

The date and time the subscription plan was last updated in ISO 8601 format.

List of subscription plan variations.

Unique identifier for the subscription plan variation.

List of billing phases for this variation.

Unique identifier for the subscription plan phase.

Possible values: >= 1

The sequential order of this phase in the subscription billing lifecycle.

Phases execute in ascending order based on this value:

  • Phase with ordinal=1 executes first
  • Phase with ordinal=2 executes second, and so on

When a phase completes its cycle_count, the subscription automatically progresses to the phase with the next ordinal value.

Example: A subscription with phases ordered as ordinal=1 (trial), ordinal=2 (regular), ordinal=3 (discounted) will progress through them in that sequence.

The length of each billing cycle for this phase in ISO 8601 duration format.

This determines how often the customer is billed during this phase. The total time spent in a phase is cycle_duration × cycle_count.

Common durations:

DurationDescription
P1M1 month
P1Y1 year
P15D15 days
P1W1 week
PT2H2 hours

Example: If cycle_duration=P1M and cycle_count=12, the customer will be billed monthly for 12 months (1 year total).

Possible values: >= 1

Number of billing cycles for this phase before moving to the next phase.

ValueBehavior
null or omittedPhase continues indefinitely. The subscription remains in this phase with no automatic progression.
Specific number (e.g., 1, 3, 12)After completing this many billing cycles, the subscription automatically moves to the next phase as determined by the ordinal field.

Example: If cycle_count=3 and cycle_duration=P1M, the subscription will complete 3 monthly cycles then move to the phase with the next highest ordinal value.

Note

If no next phase exists in after a cycle with a specific cycle_count, the subscription will automatically stop when it completes its cycles.

Subscription amount in minor currency units (e.g., cents for USD, pence for GBP).

For example, 9900 in GBP represents £99.00.

Info

Conversion between major and minor units varies by currency. For instance, 100 minor units equal £1.00 in GBP, whereas in ISK they represent 100 units. For more details, see the ISO 4217 standard.

Possible length: >= 3 characters and <= 3 characters

ISO 4217 currency code in upper case.

Info

For more information about the supported currencies, see: Help Center.
Was this page helpful?