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). These plans are designed for flexibility, allowing you to combine fixed recurring fees with unit-based or usage-based charges into a single, unified subscription.

How subscription plans work​

A subscription plan consists of four hierarchical levels:

1. Plan: The top-level container (e.g., "Standard Plan")
2. Variations: Different pricing options (e.g., monthly vs. yearly)
3. Phases: Sequential billing stages within each variation
4. Subscription items: Individual line items within a phase that define how to charge (e.g., a base fee plus per-unit charges)

Phases and billing items​

If a trial_duration is defined at the variation level, billing phases begin immediately after the trial ends. Phases execute in sequence based on their ordinal value (1, 2, 3, etc.):

Concept	Behaviour
Cycle control	Each phase has a cycle_duration (e.g., P1M for monthly). Use cycle_count to limit how many cycles occur; if null or omitted, the phase runs indefinitely.
Sequential transition	When a phase completes its cycles, the subscription advances to the next ordinal. If no next phase exists, the subscription stops automatically.
Item composition	Each phase contains one or more subscription_items defining how charges are calculated: flat items apply a fixed cost multiplied by quantity; usage items are metered at the end of the cycle based on reported consumption.

Example: Multi-item billing

A plan combining a base platform fee and monthly user licenses:

Variation: Monthly Team

Phase 1 — ordinal: 1, cycle_duration: P1M

Item	Type	amount	quantity
Base platform fee	flat	4900 (£49.00)	1
User licenses	flat	1000 (£10.00 per unit)	5

The customer is billed a fixed platform fee plus £10.00 for each of their 5 active licenses every month.

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, 2025-12-04, 2026-03-12, 2026-04-20]
Example: "2026-04-20"

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.

Pattern: Value must match regular expression ^P[0-9]+D$
Example: "P14D"

The default trial period duration for this subscription plan in ISO 8601 duration format (e.g., "P14D" for 14 days).

This value serves as the default trial duration for all subscriptions created from this plan. Individual subscriptions can override this value at creation time.

Note

Only days (D) are allowed. Time components such as hours, minutes, or seconds are not permitted.

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:

Duration	Description
P1M	1 month
P1Y	1 year
P15D	15 days
P1W	1 week
PT2H	2 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.

Value	Behavior
null or omitted	Phase 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.

A list of subscription items for this phase.

Object structure of flat subscription item.

Possible length: <= 250 characters
Example: "Base Subscription Fee"

The name of the subscription item.

Possible values: [flat, usage]
Example: "flat"

The type of subscription item.

Example: 1

The number of units grouped together as a single billable package. Used to enable pricing of items that are too inexpensive to charge individually.

For example, a package_size of 1000 with a unit price of 10 minor units (£0.10 in GBP) lets you sell 1000 tokens for £0.10 — effectively pricing each token at £0.0001, below the minimum chargeable amount.

Set to 1 to price each unit individually.

Possible length: <= 100 characters
Example: "subscription"

The unit of measurement for the item.

Example: 1

The quantity of the item.

Example: 9900

Amount in minor currency units (e.g., cents for USD).

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.

Pattern: Value must match regular expression ^P[0-9]+D$
Example: "P14D"

The default trial period duration for this subscription plan in ISO 8601 duration format (e.g., "P14D" for 14 days).

This value serves as the default trial duration for all subscriptions created from this plan. Individual subscriptions can override this value at creation time.

Note

Only days (D) are allowed. Time components such as hours, minutes, or seconds are not permitted.

Possible values: [active, deactivated]

The state of the subscription plan.

State	Description
active	The plan is active and can be used to create new subscriptions.
deactivated	The 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:

Duration	Description
P1M	1 month
P1Y	1 year
P15D	15 days
P1W	1 week
PT2H	2 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.

Value	Behavior
null or omitted	Phase 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.

A list of subscription items for this phase.

Object structure of flat subscription item.

The unique identifier of the subscription item.

Possible length: <= 250 characters
Example: "Base Subscription Fee"

The name of the subscription item.

Possible values: [flat, usage]
Example: "flat"

The type of subscription item.

Example: 1

The number of units grouped together as a single billable package. Used to enable pricing of items that are too inexpensive to charge individually.

For example, a package_size of 1000 with a unit price of 10 minor units (£0.10 in GBP) lets you sell 1000 tokens for £0.10 — effectively pricing each token at £0.0001, below the minimum chargeable amount.

Set to 1 to price each unit individually.

Possible length: <= 100 characters
Example: "subscription"

The unit of measurement for the item.

Example: 1

The quantity of the item.

Example: 9900

Amount in minor currency units (e.g., cents for USD).

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.