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

# Create a subscription plan

Create a new subscription plan with one or more pricing variations.

A subscription plan defines the billing structure for subscriptions. Each plan can have multiple variations (e.g., monthly vs. yearly), and each variation can have multiple billing phases (e.g., trial period followed by regular billing). These plans are designed for flexibility, allowing you to combine fixed recurring fees with unit-based or usage-based charges into a single, unified subscription.

## How subscription plans work

A subscription plan consists of four hierarchical levels:

1. **Plan**: The top-level container (e.g., "Standard Plan")
1. **Variations**: Different pricing options (e.g., monthly vs. yearly)
1. **Phases**: Sequential billing stages within each variation
1. **Subscription items**: Individual line items within a phase that define **how** to charge (e.g., a base fee plus per-unit charges)

### Phases and billing items

If a `trial_duration` is defined at the variation level, billing phases begin immediately after the trial ends. Phases execute in sequence based on their `ordinal` value (1, 2, 3, etc.):

| Concept | Behaviour |
| ------- | --------- |
| **Cycle control** | Each phase has a `cycle_duration` (e.g., `P1M` for monthly). Use `cycle_count` to limit how many cycles occur; if `null` or omitted, the phase runs indefinitely. |
| **Sequential transition** | When a phase completes its cycles, the subscription advances to the next `ordinal`. If no next phase exists, the subscription stops automatically. |
| **Item composition** | Each phase contains one or more `subscription_items` defining how charges are calculated: **flat** items apply a fixed cost multiplied by `quantity`; **usage** items are metered at the end of the cycle based on reported consumption. |

:::tip [Example: Multi-item billing]
A plan combining a **base platform fee** and **monthly user licenses**:

**Variation:** `Monthly Team`

**Phase 1** — `ordinal: 1`, `cycle_duration: P1M`

| Item | Type | `amount` | `quantity` |
| ---- | ---- | -------- | ---------- |
| **Base platform fee** | `flat` | `4900` (£49.00) | `1` |
| **User licenses** | `flat` | `1000` (£10.00 per unit) | `5` |

The customer is billed a fixed platform fee plus £10.00 for each of their 5 active licenses every month.
:::

## Endpoint

POST `/api/subscription-plans`

## Request body

### Attributes

- `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.
    :::
- `variations` (array of object)
    List of subscription plan variations (e.g., monthly, yearly pricing options).
  - `variations[].phases` (array of object)
      List of billing phases for this variation.
    - `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)
        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)
        [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.

## Returns

### 201

Subscription plan created 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 |