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

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

## Endpoint

GET `/api/subscriptions`

## 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**.

- `external_reference` (string, optional)
  Return subscriptions with a specific `external_reference`. 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 subscriptions retrieved successfully

#### Response attributes

- `next_page_token` (string | null, optional)
    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.
- `subscriptions` (array of object)
    List of subscriptions.
  - `subscriptions[].id` (string)
      Unique identifier for the subscription.
  - `subscriptions[].external_reference` (string, optional)
      Optional external reference for the subscription.
      
      Use this field to store your own system's identifier for easy tracking and correlation.
  - `subscriptions[].state` (enum)
      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). |
      Possible enum values:

      - `pending`
      - `active`
      - `overdue`
      - `paused`
      - `cancelled`
      - `finished`
  - `subscriptions[].customer_id` (string)
      Unique identifier for the customer.
  - `subscriptions[].plan_id` (string)
      Unique identifier for the subscription plan.
  - `subscriptions[].plan_variation_id` (string)
      Unique identifier for the subscription plan variation.
  - `subscriptions[].payment_method_type` (enum)
      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. |
      Possible enum values:

      - `automatic`
      - `manual`
  - `subscriptions[].payment_method_id` (string, optional)
      Unique identifier for the payment method.
  - `subscriptions[].created_at` (string)
      The date and time the subscription was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `subscriptions[].updated_at` (string)
      The date and time the subscription was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `subscriptions[].start_date` (string | null, optional)
      The date and time the subscription started in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      
      This field is `null` until the subscription becomes active.
  - `subscriptions[].current_cycle_id` (string)
      Unique identifier for the subscription cycle.
  - `subscriptions[].trial_duration` (string, optional)
      The trial period duration for this subscription in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g., "P14D" for 14 days).
      
      ### Override plan defaults
      
      Subscription plans can define a default trial duration. When creating a subscription, you can use this field to override the plan's default trial period:
      
      | Field value | Behaviour | Example |
      | ----------- | -------- | ------- |
      | **Not provided** | Uses the trial duration defined in the plan (if any) | Plan has `"P7D"` → subscription gets 7-day trial |
      | **Different value** | Overrides the plan's default trial duration | Plan has `"P7D"` → set to `"P30D"` for promotional offer, or `"P3D"` to reduce |
      | **`"P0D"`** | Explicitly skips the trial period | Plan has `"P7D"` → set to `"P0D"` to skip trial entirely |
      
      :::note
      Only days (`D`) are allowed. Time components such as hours, minutes, or seconds are not permitted.
      :::
  - `subscriptions[].trial_end_date` (string | null, optional)
      The date and time when the subscription's trial period ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      
      This value is automatically calculated by the system as: `start_date` + `trial_duration`
      
      The `trial_duration` used in the calculation comes from either:
      - The subscription's custom `trial_duration` (if provided at creation time), or
      - The plan's default `trial_duration` (if no override was specified)
      
      This field is `null` when the subscription has no trial period (e.g., when `trial_duration` is not set or is `"P0D"`).
  - `subscriptions[].setup_order_id` (string, optional)
      The ID of the order created for handling the setup payment for the subscription.
      
      Use the [Retrieve an order](/docs/api/merchant#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.
      
      :::note
      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.
      :::
  - `subscriptions[].scheduled_action` (object, optional)
      A pending scheduled action on the subscription, applied at the end of the current billing cycle.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |