Retrieve a subscription plan
Retrieve a specific subscription plan by its unique identifier.
A subscription plan contains variations (different pricing options like monthly vs. yearly), and each variation contains phases (sequential billing stages).
Phases execute based on their ordinal value. When a phase completes its cycle_count, the subscription moves to the next phase. If cycle_count is null or omitted, the phase continues indefinitely.
If a trial_duration is defined, phases begin immediately after the trial ends.
Request
The ID of the subscription plan.
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.
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.
For more information about API versioning, see: API versions.
Response
Subscription plan retrieved successfully
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.
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=1executes first - Phase with
ordinal=2executes 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.
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.
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.
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.
For more information about the supported currencies, see: Help Center.