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

# Retrieve a subscription plan

Retrieve a specific subscription plan by its unique identifier.

A subscription plan contains **variations** (different pricing options like monthly vs. yearly), and each variation contains **phases** (sequential billing stages).

Phases execute based on their `ordinal` value. When a phase completes its `cycle_count`, the subscription moves to the next phase. If `cycle_count` is `null` or omitted, the phase continues indefinitely.

:::note
If a `trial_duration` is defined, phases begin immediately after the trial ends.
:::

## Endpoint

GET `/api/subscription-plans/{subscription_plan_id}`

## Returns

### 200

Subscription plan retrieved successfully

#### Response attributes

- `id` (string)
    Unique identifier for the subscription plan.
- `name` (string)
    The name of the subscription plan.
- `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.
    :::
- `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`
- `created_at` (string)
    The date and time the subscription plan was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `updated_at` (string)
    The date and time the subscription plan was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `variations` (array of object)
    List of subscription plan variations.
  - `variations[].id` (string)
      Unique identifier for the subscription plan variation.
  - `variations[].phases` (array of object)
      List of billing phases for this variation.
    - `variations[].phases[].id` (string)
        Unique identifier for the subscription plan phase.
    - `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.
    - `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).
    - `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.
        :::
    - `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).
        :::
    - `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/).
        :::
    - `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 |
| 404 | Subscription plan not found |