Retrieve a subscription plan
Retrieve a specific subscription plan by its unique identifier.
Understanding subscription plan structure
A subscription plan contains variations (different pricing options like monthly vs. yearly), and each variation contains phases (sequential billing stages like trial → regular).
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, the phase continues indefinitely.
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]
Example: "2025-10-16"
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.
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.