Retrieve a subscription plan list
Retrieve all subscription plans configured for your merchant account. You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the subscription plans that you want to retrieve, for example, only retrieve plans created within a specific date range. Parameters used for filtering:
| View the subscription plans without loading all of them at once, for example, return a specified number of plans per page. Parameters used for pagination:
|
Request
Possible values: >= 1 and <= 500
Default value: 100
Maximum number of records to return. Used for pagination.
Filter records created from this date/time. Used for filtering.
Filter records created until this date/time. Used for filtering.
Token for retrieving the next page of results. Used for pagination.
To paginate through results:
- Make an initial request with the desired
limit. - The response will include a
next_page_tokenif more results are available. - Use that token in the
page_tokenparameter of your next request. - Repeat until
next_page_tokenis not present.
When using page_token, you must include all query parameters from the initial request (such as from, to, or other filter parameters) to maintain consistent filtering across pages.
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
List of subscription plans retrieved successfully
Token for retrieving the next page of results.
If not present, there are no more results to retrieve.
List of subscription plans.
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.