Retrieve a subscription list
Retrieve all subscriptions for the merchant account. You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the subscriptions that you want to retrieve, for example, only retrieve subscriptions created within a specific date range or with a specific external reference. Parameters used for filtering:
| View the subscriptions without loading all of them at once, for example, return a specified number of subscriptions 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.
Return subscriptions with a specific external_reference. 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 subscriptions retrieved successfully
Token for retrieving the next page of results. Use this token as the value of the page_token query parameter in your next request to retrieve the next page.
If not present, there are no more results to retrieve.
List of subscriptions.
Unique identifier for the subscription.
Possible length: <= 1024 characters
Optional external reference for the subscription.
Use this field to store your own system's identifier for easy tracking and correlation.
Possible values: [pending, active, overdue, paused, cancelled, finished]
The state of the subscription.
| State | Description |
|---|---|
pending | The subscription has been created but is not yet active. This typically occurs when awaiting the first payment or setup completion. |
active | The subscription is currently active and billing cycles are processing normally. |
overdue | The subscription has a failed payment and is awaiting resolution. |
paused | The subscription has been temporarily paused and no billing will occur. |
cancelled | The subscription has been cancelled and will not renew. |
finished | The subscription has completed all billing cycles (for limited-duration subscriptions). |
Unique identifier for the customer.
Unique identifier for the subscription plan.
Unique identifier for the subscription plan variation.
Possible values: [automatic, manual]
The type of payment method used for the subscription.
| Type | Description |
|---|---|
automatic | Payments are automatically charged to the customer's saved payment method. |
manual | Payments require manual processing by the customer. |
Unique identifier for the payment method.
The date and time the subscription was created in ISO 8601 format.
The date and time the subscription was last updated in ISO 8601 format.
The date and time the subscription started in ISO 8601 format.
This field is null until the subscription becomes active.
Unique identifier for the subscription cycle.
The ID of the order created for handling the setup payment for the subscription.
Use the Retrieve an order endpoint with this ID to get order details, including the checkout_url for redirecting customers to the Hosted Payment Page or the token for widget integration.
The order is created in parallel to the subscription and is used to collect the initial payment and save the customer's payment method for future billing cycles.