Retrieve a subscription cycle
Retrieve a specific billing cycle for a subscription by its unique identifier.
Use this endpoint to get the details and current state of a particular billing cycle.
Request
The ID of the subscription.
The ID of the subscription cycle.
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
Subscription cycle retrieved successfully
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.