Create a plan, subscribe a customer, and collect the first recurring payment - the flow every subscription integration builds on.
Every subscription integration follows the same core flow, whatever the pricing model.
This guide walks you through the flow once - the scenario guides vary the plan configuration for fixed-rate, per-seat, usage-based, and trial pricing.
How it works
The integration flow breaks down into the following steps:
- Create a subscription plan - define the pricing: one or more variations (e.g. monthly and yearly), each with phases that set the billing cycle and amount.
- Create a subscription - attach a customer to a plan variation. The subscription starts in
pending, and Revolut creates a setup order for the first payment. - Collect the first payment - redirect the customer to the hosted checkout page, or embed a payment widget in your site. The customer pays, and Revolut saves their payment method.
- The subscription activates - Revolut charges the saved payment method automatically on each billing cycle, and retries failed payments.
- Monitor and manage - retrieve subscriptions and billing cycles, and receive webhook events when subscription states change.
Plans, variations, and phases
Pricing details live on the plan in three nested levels.
A plan is the product you sell - "Premium plan" - and it carries one or more variations: pricing options such as monthly and yearly billing.
Each variation contains one or more phases that run in sequence - a phase sets one price (amount, in minor units) for billing cycles of a given length (cycle_duration). Single-phase variations charge the same price indefinitely; multi-phase variations change price over time, which is how introductory pricing and trials work.
In terms of the API's fields and types - as the create response returns them - the same structure looks like this:
Before you begin
Before you start integrating, make sure you have the following:
- An active Revolut Business account with a Merchant account - see Get started with the Merchant API.
- A sandbox account with API keys - see Set up a sandbox account.
- An existing customer - the customer must already exist in the API before you create a subscription. See Create a customer.
- Familiarity with the core subscription concepts - see Subscription plans and Subscription lifecycle.
Implement your first subscription
The following steps build on each other: each API call returns the IDs the next step needs, so work through them in order and save every response.
1. Create a subscription plan
You start here once you have a recurring service to sell - software access, a membership, a hosted product, anything customers pay for on an ongoing basis. Say that service is your Pro plan, billed at £99.00 a month.
The plan you create consumes these business details: the name your customers recognise, the monthly billing cadence, and the price. One variation with one phase is enough.
To understand how plans, variations, and phases relate, see Plans, variations, and phases.
Call Create a subscription plan to define a plan with the respective details:
POST /api/subscription-plans HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Content-Type: application/json
{
"name": "Pro plan",
"variations": [
{
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 9900,
"currency": "GBP"
}
]
}
]
}| Parameter | Description |
|---|---|
name | The plan name - what your customers subscribe to |
variations | Pricing options for the plan, e.g., monthly and yearly |
phases | Sequential pricing stages within a variation, executed in ordinal order |
ordinal | Execution order of the phase, starting at 1 |
cycle_duration | Length of the billing cycle, as an ISO 8601 duration, e.g., P1M |
cycle_count | Number of cycles the phase runs for - omit to run indefinitely |
amount | Price per billing cycle, in minor units - 9900 is £99.00 |
currency | Billing currency, as an ISO 4217 code |
2. Create a subscription
When a customer wants to subscribe to the Pro plan, you create a subscription. The subscription connects the customer - and their consent to use their payment details for recurring charges - to one variation of the plan, e.g., the variation for monthly billing. You identify the variation with the id you saved after creating the plan.
The customer must already exist in the API.
Once created, the subscription starts in pending state - it becomes active once the customer completes the first payment.
Call Create a subscription with an idempotency key, so you can safely retry the request without creating duplicate subscriptions:
POST /api/subscriptions HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Content-Type: application/json
Idempotency-Key: 0f7c9a1e-3f2a-4b8e-9d1c-7a2e5b8d3f10
{
"plan_variation_id": "f4e0a171-4f4e-484b-b0a2-22085059af65",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"external_reference": "cus_8f3a91",
"setup_order_redirect_url": "https://example.com/subscription/complete"
}| Parameter | Description |
|---|---|
plan_variation_id | The variation the customer subscribes to - the variation id you saved from step 1 |
customer_id | The customer to bill |
external_reference | Optional: your own identifier for the subscription, e.g., the customer's ID in your system - returned in responses and echoed in webhook events |
setup_order_redirect_url | Optional: where the customer lands after completing payment on the hosted checkout page |
3. Collect the first payment
In the previous step, you created the subscription. It is in pending state, and becomes active once the customer completes the first payment. That payment is collected through a setup order - an order that exists to start a subscription.
Revolut creates the setup order in the background when you create the subscription: it takes the first charge - £99.00 for the Pro plan - and saves the customer's payment method for the recurring cycles that follow. You already saved its setup_order_id.
3.1 Retrieve the setup order
Retrieve the setup order with Retrieve an order, passing the setup_order_id you saved in step 2 as the order_id:
GET /api/orders/{order_id} HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17| Parameter | Description |
|---|---|
order_id | The ID of the setup order you saved in step 2 |
Like the calls in the previous steps, this is a server-side operation - it happens between your backend and the Merchant API.
3.2 Build your payment acceptance solution
Collecting the payment reaches beyond your backend: the customer pays in their browser or mobile app, so this part of the flow has client-side work alongside your server. The goal is to hand the customer a way to pay the first charge and save their payment method. Revolut supports two approaches, and both do this for you:
Choose the approach that fits your integration:
Keep the customer on your site with an embedded payment widget or a card-not-present method:
- Build your payment acceptance solution on your frontend with the widget or payment method of your choice, initialising it with the
tokenfrom the response. - Configure it to save the customer's payment method for merchant-initiated recurring transactions.
- The customer completes payment without leaving your site, and Revolut saves their payment method.
This step assumes you're familiar with a standard payment method integration, see Introduction to online payments.
4. Verify subscription state
When the customer completes the first payment in step 3, the subscription becomes active. There's no webhook event for activation, so retrieve the subscription to confirm it's live.
Check the subscription details with Retrieve a subscription, passing the subscription id from step 2 as the subscription_id:
GET /api/subscriptions/{subscription_id} HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17| Parameter | Description |
|---|---|
subscription_id | The ID of the subscription you saved in step 2 |
Going forward, Revolut charges the saved payment method automatically on each billing cycle. If a renewal payment fails, the subscription moves to overdue and Revolut retries the payment - see Failed payments and retries.
If the plan includes a trial_duration, the subscription still starts in pending - but it activates as soon as the customer provides a payment method, and Revolut collects the first payment when the trial ends.
See Build a subscription with trials and introductory pricing.
You've built your first subscription! The plan exists, the customer is subscribed, the first payment is collected, and the subscription is active. With the universal flow complete, you're ready to build a specific pricing model in a scenario guide.
Implementation checklist
Confirm your integration handles the universal flow before moving on to a scenario guide. Run the checks in the Sandbox environment first - set the base URL of your API calls to sandbox-merchant.revolut.com - then repeat them in production before going live.
- Created a plan and saved the returned variation
id - Created a subscription for an existing customer - the response contains
state: "pending"and asetup_order_id - Collected the first payment via the setup order - hosted checkout or payment widget
- Retrieved the subscription and confirmed
state: "active" - Handled failed payments - a failed renewal moves the subscription to
overdue, and Revolut retries automatically
For verifying the payment solution itself - widget behaviour, test cards, webhook receipt for the order - use the implementation checklist in the payment method guide you followed.