# Introduction to the Subscriptions API

**Build subscription billing end-to-end with the Merchant API - server-to-server flows for plans, sign-up, usage reporting, and monitoring.**

These guides cover building your own server-to-server integration for Billing & subscriptions: full programmatic control over plan creation, customer sign-up, payment collection, usage reporting, and lifecycle monitoring. 

Each scenario guide implements one of the pricing models described in [Subscription plans](/docs/guides/merchant/billing-subscriptions/subscription-plans#pricing-models) - pick the one that matches your business, or combine mechanisms across guides.

:::note[Prerequisites]
These guides assume you understand the core subscription concepts - see [Subscription plans](/docs/guides/merchant/billing-subscriptions/subscription-plans) and [Subscription lifecycle](/docs/guides/merchant/billing-subscriptions/subscription-lifecycle). For account setup and API access, see [Get started](/docs/guides/merchant/get-started).
:::

## How it works

### The integration model

The subscription lifecycle - creating plans and subscriptions, reporting usage, managing and monitoring - runs server-to-server between your backend and the Merchant API. The flow has a single customer-facing touchpoint: collecting the first payment, which also saves the customer's payment method for every future charge. Revolut handles the recurring billing automatically from there.

For the customer-facing touchpoint, pick either:

- **Hosted checkout page** - redirect the customer to the `checkout_url` from the retrieved setup order. The lightest client-side work: no payment UI to build.
- **Payment widget** - retrieve the setup order's `token` and integrate the payment method of your choice into your checkout.

```mermaid
flowchart LR
    subgraph B["Your backend - server-to-server"]
        direction TB
        b1["Create plans, subscriptions,<br/>and usage reports"]
        b2["Manage and monitor<br/>subscriptions"]
        b1 --> b2
    end

    subgraph R["Revolut"]
        direction TB
        r1["Merchant API"]
        r2["Billing engine - saved payment<br/>methods, automatic charges, retries"]
        r1 --> r2
    end

    subgraph T["Customer touchpoint - pick one"]
        direction TB
        t1["Redirect to checkout_url -<br/>hosted checkout page"]
        t2["Initialise a payment widget<br/>with the order token"]
        t1 --> t2
    end

    %% Invisible edges control group and tile order - do not remove
    B --> R
    R --> T
    linkStyle default stroke:transparent,stroke-width:0
```

| Area | What Revolut handles | What you build |
|------|----------------------|----------------|
| Recurring billing | Payment scheduling, automatic charges, retries, payment method storage | Nothing - the billing engine runs on Revolut's side |
| Subscription lifecycle | State management, billing cycles, state-change webhook events | Respond to states: provision access, handle failed payments |
| Plans and pricing | Plan storage - the variation and phase model | Plan configuration that matches your pricing, via API calls |
| First payment | Setup order creation, payment processing, payment method saving | The customer-facing payment step - a redirect or a widget |

:::info
These guides assume you're familiar with a standard payment method integration, see [Introduction to online payments](/docs/guides/merchant/accept-payments/online-payments/introduction).
:::

### API vs no-code

The API path trades dashboard convenience for control. You automate plan management and usage reporting, build your own sign-up experience, and receive webhook events for subscription state change.

:::info
For the complete side-by-side comparison of the two approaches, see [Choose your approach](/docs/guides/merchant/billing-subscriptions/introduction#choose-your-approach).
:::

| Capability | No-code | API |
|------------|---------|-----|
| Customer sign-up | Hosted payment page you share via a link | Checkout flow you build and control |
| Plan management | Dashboard | Programmatic - automate and sync with your systems |
| Usage reporting | Not available in the dashboard | Report usage via the API |
| Webhooks | Not available | Real-time subscription events |
| Customisation | Hosted page branding | Full control over the customer experience |

:::tip[Same infrastructure]
Both approaches operate on the same plans and subscriptions - anything you create in the [Revolut Business dashboard](https://business.revolut.com/merchant/subscriptions) is visible via the API, and vice versa. You can start no-code and move to the API without migrating your subscriptions.
:::

### Your pricing model

The following scenario guides align with the pricing models described in [Subscription plans](/docs/guides/merchant/billing-subscriptions/subscription-plans#pricing-models). The table below shows how the API bills each model and which guide covers it.

| Pricing model | How the API bills it | Guide |
|---------------|----------------------|-------|
| Fixed / flat-rate recurring | One price per billing cycle, charged automatically | [Build a fixed-rate subscription](/docs/guides/merchant/billing-subscriptions/api/fixed) |
| Per-seat with a stable seat count | Per-seat price for a fixed seat count | [Build a per-seat subscription](/docs/guides/merchant/billing-subscriptions/api/per-seat) |
| Per-seat with seats changing during the cycle | You report the current seat count; billed on the reported value | [Build a per-seat subscription](/docs/guides/merchant/billing-subscriptions/api/per-seat) |
| Usage-based metered, per unit or in volume tiers | You report usage as it happens; priced per unit or in volume tiers | [Build a usage-based subscription](/docs/guides/merchant/billing-subscriptions/api/usage-based) |
| Peak usage, e.g. concurrent connections | Billed on the highest usage reported in the cycle | [Build a usage-based subscription](/docs/guides/merchant/billing-subscriptions/api/usage-based) |
| Free trials | Free period before the first charge; set on the plan or per subscription | [Build a subscription with trials and introductory pricing](/docs/guides/merchant/billing-subscriptions/api/trials) |
| Introductory & promotional phases | Price changes automatically after a set number of billing cycles | [Build a subscription with trials and introductory pricing](/docs/guides/merchant/billing-subscriptions/api/trials) |

:::tip[Combine pricing models]
You can combine mechanisms in a single plan - for example, a fixed base rate plus per-seat pricing, with a free trial for the first 14 days. Each guide notes where its model combines with others.
:::

### Guide roadmap

Integrating with the subscriptions API is a three-step process:

#### 1. Get started [!step]

- [:Rocket: Get started](/docs/guides/merchant/billing-subscriptions/api/get-started 'Create your first plan and subscription, and collect the first payment')

#### 2. Build your integration [!step]

- [:Repayment: Build a fixed-rate subscription](/docs/guides/merchant/billing-subscriptions/api/fixed 'Charge a fixed recurring amount - the simplest subscription flow')
- [:PlaneSeat: Build a per-seat subscription](/docs/guides/merchant/billing-subscriptions/api/per-seat 'Bill per seat, with a stable or changing seat count')
- [:LimitHigh: Build a usage-based subscription](/docs/guides/merchant/billing-subscriptions/api/usage-based 'Meter usage, report it via the API, and settle charges at cycle end')
- [:Voucher: Build a subscription with trials](/docs/guides/merchant/billing-subscriptions/api/trials 'Offer free trials and promotional pricing phases')

#### 3. Track subscriptions with webhooks [!step]

- [:Webhook: Track subscriptions with webhooks](/docs/guides/merchant/billing-subscriptions/api/webhooks 'Receive real-time events when subscription states change')

<!--
TODO (PTTD-824)

Lifecycle management operations (change plan, change renewal date, payment method updates,
cancellation details, dunning) are deferred to the upcoming manage/ category per the roadmap in
../introduction.md - add links from this page when those pages land. Do not link them here yet.
-->

## What's next

- [:Rocket: Get started](/docs/guides/merchant/billing-subscriptions/api/get-started 'Create your first subscription with the Merchant API')
- [:AddProduct: Subscription plans](/docs/guides/merchant/billing-subscriptions/subscription-plans 'Understand plans, variations, phases, and pricing models')
- [:Workflow: Subscription lifecycle](/docs/guides/merchant/billing-subscriptions/subscription-lifecycle 'Learn about subscription states and transitions')