---
api: 'Merchant API'
---

# 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. <br/><br/>Parameters used for filtering:<br/><ul><li>`from`</li><li>`to`</li></ul> | View the subscription cycles without loading all of them at once, for example, return a specified number of cycles per page. <br/><br/>Parameters used for pagination: <br/><ul><li>`limit`</li><li>`page_token`</li></ul> |

## Endpoint

GET `/api/subscriptions/{subscription_id}/cycles`

## Parameters

### query parameters

- `limit` (integer, optional)
  Maximum number of records to return. Used for **pagination**.

- `from` (string, optional)
  Filter records created from this date/time. Used for **filtering**.

- `to` (string, optional)
  Filter records created until this date/time. Used for **filtering**.

- `page_token` (string, optional)
  Token for retrieving the next page of results. Used for **pagination**.
  
  To paginate through results:
  
    1. Make an initial request with the desired `limit`.
    1. The response will include a `next_page_token` if more results are available.
    1. Use that token in the `page_token` parameter of your next request.
    1. 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.
  :::

## Returns

### 200

List of subscription cycles retrieved successfully

#### Response attributes

- `next_page_token` (string | null, optional)
    Token for retrieving the next page of results.
    
    If not present, there are no more results to retrieve.
- `cycles` (array of object)
    List of subscription cycles.
  - `cycles[].id` (string)
      Unique identifier for the subscription cycle.
  - `cycles[].subscription_id` (string)
      Unique identifier for the subscription.
  - `cycles[].plan_variation_id` (string)
      Unique identifier for the subscription plan variation.
  - `cycles[].plan_variation_phase_id` (string, optional)
      Unique identifier for the subscription plan phase.
  - `cycles[].number` (integer)
      The sequential cycle number within the subscription.
      
      Starts at `1` for the first cycle and increments with each new billing cycle.
  - `cycles[].previous_cycle_id` (string | null, optional)
      The unique identifier of the previous billing cycle.
      
      This field is `null` for the first cycle in a subscription.
  - `cycles[].state` (enum)
      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. |
      Possible enum values:

      - `pending`
      - `active`
      - `finished`
  - `cycles[].start_date` (string, optional)
      The date and time the subscription cycle starts in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `cycles[].end_date` (string, optional)
      The date and time the subscription cycle ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `cycles[].usage_cutoff_date` (string, optional)
      The deadline for submitting or correcting usage records for this cycle, in [ISO 8601](https://en.wikipedia.org/wiki/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.
      
      :::note
      Only present for cycles that include usage-based subscription items.
      :::
  - `cycles[].order_id` (string, optional)
      Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
  - `cycles[].post_billing_order_id` (string, optional)
      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. |
      
      :::note
      Only present for cycles that include usage-based subscription items.
      :::
  - `cycles[].trial` (boolean, optional)
      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.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Subscription not found |