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

# Retrieve a subscription plan list

Retrieve all subscription plans configured for your merchant account. You can use the query parameters for:

  | Filtering | Pagination |
  | --------- | ---------- |
  | Filter the subscription plans that you want to retrieve, for example, only retrieve plans created within a specific date range. <br/><br/>Parameters used for filtering:<br/><ul><li>`from`</li><li>`to`</li></ul> | View the subscription plans without loading all of them at once, for example, return a specified number of plans per page. <br/><br/>Parameters used for pagination: <br/><ul><li>`limit`</li><li>`page_token`</li></ul> |

## Endpoint

GET `/api/subscription-plans`

## 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 plans 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.
- `subscription_plans` (array of object)
    List of subscription plans.
  - `subscription_plans[].id` (string)
      Unique identifier for the subscription plan.
  - `subscription_plans[].name` (string)
      The name of the subscription plan.
  - `subscription_plans[].trial_duration` (string, optional)
      The default trial period duration for this subscription plan in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g., "P14D" for 14 days).
      
      This value serves as the default trial duration for all subscriptions created from this plan. Individual subscriptions can override this value at creation time.
      
      :::note
      Only days (`D`) are allowed. Time components such as hours, minutes, or seconds are not permitted.
      :::
  - `subscription_plans[].state` (enum)
      The state of the subscription plan.
      
      | State | Description |
      | ----- | ----------- |
      | `active` | The plan is active and can be used to create new subscriptions. |
      | `deactivated` | The plan has been deactivated and cannot be used for new subscriptions. |
      Possible enum values:

      - `active`
      - `deactivated`
  - `subscription_plans[].created_at` (string)
      The date and time the subscription plan was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `subscription_plans[].updated_at` (string)
      The date and time the subscription plan was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `subscription_plans[].variations` (array of object)
      List of subscription plan variations.
    - `subscription_plans[].variations[].id` (string)
        Unique identifier for the subscription plan variation.
    - `subscription_plans[].variations[].phases` (array of object)
        List of billing phases for this variation.
      - `subscription_plans[].variations[].phases[].id` (string)
          Unique identifier for the subscription plan phase.
      - `subscription_plans[].variations[].phases[].ordinal` (integer)
          The sequential order of this phase in the subscription billing lifecycle.
          
          Phases execute in ascending order based on this value:
          - Phase with `ordinal=1` executes first
          - Phase with `ordinal=2` executes second, and so on
          
          When a phase completes its `cycle_count`, the subscription automatically progresses to the phase with the next `ordinal` value.
          
          **Example**: A subscription with phases ordered as `ordinal=1` (trial), `ordinal=2` (regular), `ordinal=3` (discounted) will progress through them in that sequence.
      - `subscription_plans[].variations[].phases[].cycle_duration` (string)
          The length of each billing cycle for this phase in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations).
          
          This determines how often the customer is billed during this phase. The total time spent in a phase is `cycle_duration × cycle_count`.
          
          **Common durations**:
          
          | Duration | Description |
          | -------- | ----------- |
          | `P1M` | 1 month |
          | `P1Y` | 1 year |
          | `P15D` | 15 days |
          | `P1W` | 1 week |
          | `PT2H` | 2 hours |
          
          **Example**: If `cycle_duration=P1M` and `cycle_count=12`, the customer will be billed monthly for 12 months (1 year total).
      - `subscription_plans[].variations[].phases[].cycle_count` (integer | null, optional)
          Number of billing cycles for this phase before moving to the next phase.
          
          | Value | Behavior |
          | ----- | -------- |
          | `null` or omitted | Phase continues indefinitely. The subscription remains in this phase with no automatic progression. |
          | Specific number (e.g., `1`, `3`, `12`) | After completing this many billing cycles, the subscription automatically moves to the next phase as determined by the `ordinal` field. |
          
          **Example**: If `cycle_count=3` and `cycle_duration=P1M`, the subscription will complete 3 monthly cycles then move to the phase with the next highest `ordinal` value.
          
          :::note
          If no next phase exists in after a cycle with a specific `cycle_count`, the subscription will automatically stop when it completes its cycles.
          :::
      - `subscription_plans[].variations[].phases[].amount` (integer, optional)
          Subscription amount in minor currency units (e.g., cents for USD, pence for GBP).
          
          For example, `9900` in `GBP` represents £99.00.
          
          :::info
          Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217).
          :::
      - `subscription_plans[].variations[].phases[].currency` (string, optional)
          [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.
          
          :::info
          For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/).
          :::
      - `subscription_plans[].variations[].phases[].subscription_items` (array of object, optional)
          A list of subscription items for this phase.

## Error responses

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