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 - pick the one that matches your business, or combine mechanisms across guides.

Prerequisites

These guides assume you understand the core subscription concepts - see Subscription plans and Subscription lifecycle. For account setup and API access, see 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.

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

These guides assume you're familiar with a standard payment method integration, see Introduction to online payments.

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.

For the complete side-by-side comparison of the two approaches, see 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

Same infrastructure

Both approaches operate on the same plans and subscriptions - anything you create in the Revolut Business dashboard 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. 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
Per-seat with a stable seat count	Per-seat price for a fixed seat count	Build a per-seat subscription
Per-seat with seats changing during the cycle	You report the current seat count; billed on the reported value	Build a per-seat subscription
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
Peak usage, e.g. concurrent connections	Billed on the highest usage reported in the cycle	Build a usage-based subscription
Free trials	Free period before the first charge; set on the plan or per subscription	Build a subscription with trials and introductory pricing
Introductory & promotional phases	Price changes automatically after a set number of billing cycles	Build a subscription with trials and introductory pricing

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.