Let customers try before they pay - or start them on a discounted introductory price that steps up to the regular rate.
A trial gives customers the product for free for a stretch of time - the first payment lands only when the trial ends. Introductory pricing gives them a discounted start - a promotional first cycle or two at a lower price, stepping up to the regular rate automatically. The Subscriptions API supports both, and they combine: a customer can try your service for free with a trial period, then pass through a promotional phase, then settle into the regular price.
In this guide, you'll sell a Premium plan - £19.00 a month with a 14-day free trial as the plan's default. One variation charges the regular price throughout; a second starts new customers on a discounted £9.90 first month. The guide signs up a new customer - no payment method on file yet - with a 30-day promotional trial in place of the plan's default, and collects their payment method through the same setup-order flow every subscription uses.
How it works
This guide walks you through the full flow: all API calls run between your backend and the Merchant API, and only one part - step 3, collecting the payment method - happens on the customer's device.
- Create the plan - the Premium plan carries a 14-day free trial, and one variation starts new customers on a discounted first month.
- Subscribe the customer - the trial starts with the subscription: the customer has no saved payment method, so it starts
pendingwith the trial running; attaching a payment method that's already on file instead activates it immediately. You can also override or skip the trial per customer. - Collect the payment method - through the setup order, same as in other subscription flows: the trial buys time, and the subscription activates the moment the method is saved - nothing is collected until the trial ends.
- Bill regularly - nothing is billed during the trial; the first payment lands when it ends, and every cycle after bills automatically.
The trial's timeline is shaped by two optional settings - offer a free trial, introductory pricing, or both:
| Mechanism | Set on | Bills during | Ends when |
|---|---|---|---|
| Free trial | The plan - trial_duration - overridable per subscription | Nothing | The trial ends and the first payment is collected |
| Introductory pricing | A variation - sequential phases | The phase's discounted amount | The phase's cycle_count completes and the next phase's price applies |
The Premium plan carries its 14-day free trial alongside the variations customers subscribe to - trial_duration is a plan-level attribute, one setting that applies to every subscription within that plan. On the subscription, the trial doesn't add a cycle of its own: cycles keep their standard duration and count, and a cycle that starts inside the trial period - before the subscription's trial_end_date - is simply flagged trial: true. Nothing is billed until the trial ends; the subscribed variation's phases set the price from the following cycle on.
The trial delays the first payment, not the payment method collection.
Collect payment details during sign-up - the subscription activates as soon as it's on file, and the first payment then waits for the trial to end without the customer needing to visit again.
Before you begin
- You've completed Get started with the Subscriptions API - it introduces the universal subscription flow this guide builds on
- Familiarity with the core subscription concepts - see Subscription plans and Subscription lifecycle
- A customer to subscribe - the walkthrough signs up a new one with no saved payment method; see Get started with the Subscriptions API for creating customers
Implement subscription with trials
The steps below follow the Premium plan narrative: the plan carries the trial default, a new customer subscribes to the Standard variation with a 30-day promotional override, and the subscription starts pending - with the trial already running - until their payment method lands in step 3.
1. Create plan with trial duration
Trials and introductory pricing are set at different levels of the plan. trial_duration lives on the plan itself - a free period that applies to every subscription unless overridden. Introductory pricing lives on a variation - sequential phases, each holding a price for a number of cycles. One plan can carry both.
For the plan, variation, and phase hierarchy these fields sit in, see Get started with the Subscriptions API.
Call Create a subscription plan to turn your trial terms and pricing steps into a subscribable plan:
POST /api/subscription-plans HTTP/1.1
Content-Type: application/json
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.com
{
"name": "Premium",
"trial_duration": "P14D",
"variations": [
{
"name": "Standard",
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 1900,
"currency": "GBP"
}
]
},
{
"name": "Intro pricing",
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1M",
"cycle_count": 1,
"amount": 990,
"currency": "GBP"
},
{
"ordinal": 2,
"cycle_duration": "P1M",
"amount": 1900,
"currency": "GBP"
}
]
}
]
}| Parameter | Description |
|---|---|
name | Plan name shown in the Revolut Business dashboard |
trial_duration | Free trial before the first payment - P14D sets 14 days as the plan's default, applying to every subscription unless overridden at creation; days only |
variations | Pricing paths customers subscribe to - one charges the regular price throughout, the other runs the introductory sequence |
phases | Sequential price steps on a variation, executed in ordinal order |
ordinal | Position of the phase in the sequence |
cycle_duration | Length of each billing cycle in the phase - P1M for monthly |
cycle_count | Cycles the phase runs before moving to the next - omit on the final phase to continue indefinitely |
amount | Price per cycle in minor units - 1900 is £19.00 |
currency | ISO 4217 currency code |
Phases run in ordinal order. cycle_count bounds a phase: the intro-pricing variation's phase 1 runs a single £9.90 cycle, then phase 2 takes over at £19.00 a month, indefinitely - omit cycle_count on a final phase and it simply never ends. When a bounded phase completes with no successor, the subscription automatically stops - that's how you shape a fixed-length plan.
The trial runs before any phase: on the intro-pricing variation, the 14-day trial bills nothing, then the £9.90 phase 1 cycle starts - the first payment that variation ever collects is the discounted one.
2. Subscribe customer
Subscribing connects the customer to one variation, and the plan's trial applies by default. The walkthrough's customer has no saved payment method, so the subscription starts pending - the trial already running - until step 3 delivers one. The other trial-specific move happens on this same call: overriding the trial length.
trial_duration on the request | Behaviour |
|---|---|
| Omitted | The plan's default applies - 14 days here |
| Same value as the plan default | Explicit restatement of the default |
| Different value | Overrides the plan default for this subscription only - the walkthrough's P30D promotional trial |
"P0D" | Skips the trial - regular billing starts immediately |
Call Create a subscription to start the customer's trial - set the 30-day promotional trial with trial_duration:
POST /api/subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer sk_abcdef12347890_...
Idempotency-Key: cd391ee6-eb5f-4124-98e1-13b76d79fa3b
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.com
{
"plan_variation_id": "31003a04-e0ca-4513-a1fb-64a6c37198ee",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"trial_duration": "P30D",
"external_reference": "promo_a3e71c",
"setup_order_redirect_url": "https://example.com/subscription/complete"
}| Parameter | Description |
|---|---|
plan_variation_id | ID of the variation the customer subscribes to - the Standard variation created in step 1: this customer's promotion is the 30-day trial itself, and the intro-pricing variation takes its turn in Change plan |
customer_id | ID of the customer subscribing - no saved payment method needed yet |
trial_duration | Overrides the plan's 14-day default - P30D gives this customer a 30-day promotional trial; "P0D" skips the trial; omitted, the plan default applies |
external_reference | Your identifier for the subscription, useful for reconciliation |
setup_order_redirect_url | Optional: where the customer lands after completing checkout in step 3 |
To start a customer on regular billing with no trial at all, send the same call with "trial_duration": "P0D" - the trial is skipped and billing begins immediately.
If the customer already has a payment method on file, attach its payment_method_id on this request - the subscription skips pending and activates immediately, and you can skip step 3.
The trial still applies either way: the first payment waits for it to end.
3. Collect payment method
In the previous step, you created the subscription. It is in pending state, and becomes active once the customer provides a payment method. That happens 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. For a trial subscription it saves the customer's payment method and collects no charge: nothing is billed during the trial, and the first £19.00 lands when the trial ends, charged by the trial cycle's order under Operate. 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 method reaches beyond your backend: the customer acts 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 authorise 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 authorisation without leaving your site, and Revolut saves their payment method - the subscription activates on the spot, and the first payment still waits for the trial to end.
This step assumes you're familiar with a standard payment method integration, see Introduction to online payments.
A pending subscription that never receives a payment method is cancelled without ever going live - the trial doesn't extend that window. See Subscription lifecycle.
4. Verify subscription state
When the customer completes authorisation in step 3, the saved payment method activates the subscription. Confirm it's live and the trial is running by calling Retrieve a subscription, passing the subscription id you saved in step 2 as the subscription_id:
GET /api/subscriptions/{subscription_id} HTTP/1.1
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.com| Parameter | Description |
|---|---|
subscription_id | The ID of the subscription you saved in step 2 |
The subscription is live: active with the trial running to trial_end_date, and no payment collected yet.
You've completed the trial subscription flow! The Premium plan is live with its two variations, the customer's payment method is saved, and their trial is running to its end date.
Next, operate the subscription: retrieve the billing cycles as the trial turns into regular billing, change the customer's plan when they need different pricing, and cancel the subscription when they leave.
From here the timeline runs itself - we collect the first payment from the saved method at trial end, bill every cycle after, and retry failed payments automatically, see Failed payments and retries.
Operate subscription with trials
The trial runs on our side - no payment is collected until trial_end_date, and billing is automatic afterwards. What stays yours: retrieving the cycles to see the trial turn into regular billing - and running entitlement checks against them - moving the customer to a different variation, and cancelling when they leave.
Retrieve billing cycles
Every cycle carries a trial flag - true while the cycle sits inside the trial period, before trial_end_date. The trial cycle bills nothing during the trial; its order collects the first payment when the trial ends. Retrieve the cycles to watch that transition:
Retrieve cycle list
Retrieve the cycles with Retrieve a subscription cycle list, passing the subscription id you saved in step 2 as the subscription_id - the trial cycle sits beside the current one:
GET /api/subscriptions/{subscription_id}/cycles HTTP/1.1
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.comRead the pair in order: cycle 1 - trial: true, finished - holds the order that collected the first £19.00 when the trial ended; cycle 2 - trial: false, current - carries the ongoing charge. A trial can end inside its cycle: trial_end_date says when the first payment is collected, while the cycle still spans its full cycle_duration - here the trial ends a day before cycle 1 closes.
Run entitlement check
Grant access while the subscription is active and its current cycle is too. The walkthrough customer is past the trial now - retrieve their current cycle with Retrieve a subscription cycle, passing its id - the current_cycle_id from the subscription response - as the cycle_id, and check the state:
GET /api/subscriptions/{subscription_id}/cycles/{cycle_id} HTTP/1.1
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.comThe check works unchanged during a trial: the current cycle is then the trial cycle - trial: true, nothing collected yet - and it still reads active, so access continues through the trial without a special case.
Change plan
When a customer outgrows the current pricing or you owe them a win-back, move them to another variation with Change a subscription plan, passing the subscription id you saved in step 2 as the subscription_id. The walkthrough customer moves to the intro-pricing variation - its £9.90 phase 1 doubles as the promotional month - scheduled to start at the end of the current cycle:
POST /api/subscriptions/{subscription_id}/change-plan HTTP/1.1
Content-Type: application/json
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.com
{
"plan_variation_id": "dc27fea7-268c-4ae8-a657-95fe7bbd535f",
"scheduled": "at_cycle_end"
}| Parameter | Description |
|---|---|
plan_variation_id | ID of the variation the customer moves to - the intro-pricing variation created in step 1 |
scheduled | When the change takes effect - at_cycle_end only: the current cycle completes at its current price and the new variation starts with the next cycle |
Plan changes are scheduled, never immediate - requesting one returns 400 immediate_not_supported. Three rules govern the move:
- Trials don't repeat - if the target variation carries a trial period, it's skipped: trials only apply when a subscription is first created.
- Multi-phase targets start from a phase - when the target variation has multiple phases, set
plan_variation_phase_idto start from a specific one; omitted, the change starts from the first phase. The walkthrough starts at the £9.90 phase 1 deliberately - point at phase 2 to skip the discount. - The current cycle completes normally - the new price applies from the next cycle, so nothing is charged twice or refunded mid-cycle.
Cancel subscription
When the customer leaves, cancel with Cancel a subscription, passing the subscription id you saved in step 2 as the subscription_id:
POST /api/subscriptions/{subscription_id}/cancel HTTP/1.1
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Host: merchant.revolut.comThe subscription moves to cancelled - a final state: it can't be reactivated, so if the customer returns, create a new subscription for them. A SUBSCRIPTION_CANCELLED webhook event is sent whether the cancellation came from you or the customer - see Subscription states and Track subscriptions with webhooks.
Cancelling during the trial costs the customer nothing - no payment has been collected yet, and none will be: Revolut stops billing and cancels any pending orders, so the first payment due at trial_end_date is never taken.
If you run the entitlement check, this is where it stops granting access: end access immediately, or - if you let customers finish what they paid for - stop at the current cycle's end_date. Cancelling stops future charges only - it doesn't refund completed cycles.
Implementation checklist
Confirm your trials integration works end to end. 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 with a
trial_durationdefault and saved both variationids - the one the customer subscribes to, and the multi-phase one for plan changes - Subscribed a customer without a saved payment method -
pendingwith the trial running,trial_durationandsetup_order_idon the response - Collected the payment method through the setup order - the order carries
amount: 0, and retrieving the subscription confirmsactivewith the first payment still waiting fortrial_end_date - Subscribed a returning customer by attaching
payment_method_idat creation -activeimmediately, no setup order needed - Overrode the trial on another subscription - omitted so the plan default applies, a different value next, then
"P0D"to skip it entirely - Retrieved the cycle list - the trial cycle shows
trial: true, and its order collected the first payment when the trial ended - Ran the entitlement check against the current cycle - and confirmed it works unchanged during the trial
- Scheduled a plan change to a multi-phase variation -
at_cycle_endonly,plan_variation_phase_idtargets the right phase, and the trial doesn't repeat on the change - Cancelled a test subscription during its trial -
204response, the first payment due attrial_end_dateis never taken, no new cycles created,SUBSCRIPTION_CANCELLEDevent received
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.