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:
| 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:
|
Request
The ID of the subscription.
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, 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
List of subscription cycles retrieved successfully
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. A cycle can enter this state automatically when usage is reported for a future cycle via POST /api/subscription-usages. |
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.
The deadline for submitting or correcting usage records for this cycle, in ISO 8601 format.
Set to 12 hours after the cycle's end_date by default. After this time, Revolut aggregates all reported usage records and creates the post_billing_order_id to initiate the charge.
Only present for cycles that include usage-based subscription items.
Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
The ID of the order created after the cycle's usage_cutoff_date to charge usage-based items accumulated during the cycle.
| Scenario | Detail |
|---|---|
| Ongoing subscription | This order also acts as the next cycle's order_id, combining usage post-billing for the current cycle with pre-billing for the next. |
| Last cycle | A standalone finishing order is created to charge all usage from this cycle. |
| Subscription ended with unpaid cycles | The finishing order consolidates all outstanding usage charges, including any from previous cycles where payment failed. |
Only present for cycles that include usage-based subscription items.
Example: false
Default value: false
Indicates whether this billing cycle occurs during the subscription's trial period.
This value is automatically calculated by the system based on the cycle's timing relative to the subscription's trial period. Returns true if the cycle is within the trial period (before trial_end_date), otherwise false.
Trial cycles typically have different billing behavior, such as reduced or zero charges.