Retrieve a subscription cycle list

Retrieve all billing cycles for a specific subscription.

You can use the query parameters for:

Filtering	Pagination
Filter the subscription cycles that you want to retrieve, for example, only retrieve cycles that started within a specific date range. Parameters used for filtering: from to	View the subscription cycles without loading all of them at once, for example, return a specified number of cycles per page. Parameters used for pagination: limit page_token

Request​

Path parameters

Path parameters

The ID of the subscription.

Query parameters

Query parameters

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:

1. Make an initial request with the desired limit.
2. The response will include a next_page_token if more results are available.
3. Use that token in the page_token parameter of your next request.
4. Repeat until next_page_token is not present.

Note

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.

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]
Example: "2025-10-16"

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.

Response​

List of subscription cycles retrieved successfully

Response body

Body object

Token for retrieving the next page of results.

If not present, there are no more results to retrieve.

List of subscription cycles.

Unique identifier for the subscription cycle.

Unique identifier for the subscription.

Unique identifier for the subscription plan variation.

Unique identifier for the subscription plan phase.

Possible values: >= 1

The sequential cycle number within the subscription.

Starts at 1 for the first cycle and increments with each new billing cycle.

The unique identifier of the previous billing cycle.

This field is null for the first cycle in a subscription.

Possible values: [pending, active, finished]

The state of the subscription cycle.

State	Description
pending	The cycle has been created but has not yet started.
active	The cycle is currently active and in progress.
finished	The cycle has completed.

The date and time the subscription cycle starts in ISO 8601 format.

The date and time the subscription cycle ends in ISO 8601 format.

Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.