Need help with your APIs? I offer API discovery, governance & evangelism services. Explore services →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

Revolut Subscriptions API

The Subscriptions API provides a complete solution for creating and managing recurring billing for your customers.You can automatically charge customers on flexible billing cycles, manage sophisticated subscription plans, and track the entire billing history for every subscriber.## How it works?A subscription's billing structure is defined by a **Subscription plan**. This model gives you granular control:- **Plans** contain one or more **variations** (e.g., a "Gold" plan could have "Monthly" and "Yearly" variations).- **Variations** can have multiple **phases** (e.g., a 7-day free trial followed by a regular billing phase).This powerful structure allows you to build complex pricing models, including free trials, introductory offers, and tiered pricing.## Key features- **Flexible pricing models:** Create plans with multiple variations and phases to support any billing scenario.- **Automated charging:** Automatically charge a customer's saved payment method at the start of each billing cycle.- **Hosted onboarding:** For new customers, generate a setup order with a redirect URL to Revolut's Hosted Payment Page, allowing them to securely add a payment method.- **Lifecycle tracking:** Monitor each billing cycle's state, view all associated orders, and access complete payment histories.- **Full subscription management:** Easily update customer payment methods, cancel subscriptions, and view a complete billing history.

Revolut Subscriptions API is one of 46 APIs that Revolut publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include Subscriptions. The published artifact set on APIs.io includes an OpenAPI specification.

This API exposes 17 operations across 11 paths, and defines 85 schemas. It is described by OpenAPI 3.0.1, at version 1.0.

Requests are made against 2 base URLs: https://b2b.revolut.com/api/1.0, https://sandbox-b2b.revolut.com/api/1.0.

17 operations 11 paths 85 schemas 1 DELETE8 GET2 PATCH6 POST

Metadata

The identity and technical contract details declared by the specification.

Specification
OpenAPI 3.0.1
API Version
1.0
Base URL
https://b2b.revolut.com/api/1.0
Authentication
HTTP Bearer
Resource Areas
1

Authentication & Security 1

Revolut Subscriptions API declares 1 security scheme for authenticating requests. It accepts HTTP bearer tokens (AccessToken).

  • AccessToken — Each Business API request must contain an authorization header in the following format to make a call: Bearer . The access token will be obtained the first tim…

Paths & Operations 17

Across 11 paths, the API surfaces 17 operations — 1 DELETE, 8 GET, 2 PATCH, 6 POST. Each is listed below with its method, path, parameters, and response codes.

Subscriptions 17

The Subscriptions API provides a complete solution for creating and managing recurring billing for your customers. You can automatically charge customers on flexible billing cycle…

POST
/api/subscription-plans
Create a subscription plan
createSubscriptionPlan 2 params body → 201400401default
GET
/api/subscription-plans
Retrieve a subscription plan list
retrieveSubscriptionPlanList 6 params → 200400401default
GET
/api/subscription-plans/{subscription_plan_id}
Retrieve a subscription plan
retrieveSubscriptionPlan 3 params → 200400401404default
POST
/api/subscriptions
Create a subscription
createSubscription 3 params body → 201400401default
GET
/api/subscriptions
Retrieve a subscription list
retrieveSubscriptionList 7 params → 200400401default
GET
/api/subscriptions/{subscription_id}
Retrieve a subscription
retrieveSubscription 3 params → 200400401404default
PATCH
/api/subscriptions/{subscription_id}
Update a subscription
updateSubscription 3 params body → 200400401404default
POST
/api/subscriptions/{subscription_id}/change-plan
Change a subscription plan
changeSubscriptionPlan 3 params body → 204400401404422default
POST
/api/subscriptions/{subscription_id}/change-renewal-date
Update a subscription renewal date
updateSubscriptionRenewalDate 3 params body → 204400401404422default
POST
/api/subscriptions/{subscription_id}/cancel
Cancel a subscription
cancelSubscription 3 params → 204400401404default
GET
/api/subscriptions/{subscription_id}/cycles
Retrieve a subscription cycle list
retrieveSubscriptionCycleList 7 params → 200400401404default
GET
/api/subscriptions/{subscription_id}/cycles/{cycle_id}
Retrieve a subscription cycle
retrieveSubscriptionCycle 4 params → 200400401404default
POST
/api/subscription-usages
Create a subscription usage
createSubscriptionUsage 3 params body → 201400401422default
GET
/api/subscription-usages
Retrieve a subscription usage list
retrieveSubscriptionUsageList 8 params → 200400401default
GET
/api/subscription-usages/{usage_id}
Retrieve a subscription usage
retrieveSubscriptionUsage 3 params → 200400401404default
PATCH
/api/subscription-usages/{usage_id}
Update a subscription usage
updateSubscriptionUsage 3 params body → 200400401404422default
DELETE
/api/subscription-usages/{usage_id}
Delete a subscription usage
deleteSubscriptionUsage 3 params → 204400401404422default

Schemas 85

The contract defines 85 schemas that model the data the API accepts and returns. The most detailed are Subscription (16 properties), Subscription-Cycle (13 properties), Subscription-Item-Usage (10 properties), Subscription-Item-Usage-Creation (9 properties). Each schema is shown below with its type and property counts.

Subscription-Scheduled-Action-Cancel
object
A cancellation scheduled to take effect at the end of the current billing cycle.
2 properties 2 required
Subscription-Update-Renewal-Date
object
1 property 1 required
Subscription-Items-Creation
array
A list of subscription items for this phase.
Setup-Order-Id
string
The ID of the order created for handling the setup payment for the subscription. Use the [Retrieve an order](https://developer.revolut.com/docs/api/merchantret…
Subscription-Usage-Update
object
2 properties
Subscription-Usage-Quantity
number
The quantity of consumption to record for this usage report. Supports up to 20 digits before and 20 digits after the decimal point.
Subscription
object
16 properties 9 required
Subscription-Item-Tier
object
2 properties 1 required
Cycle-Count
integer
Number of billing cycles for this phase before moving to the next phase. | Value | Behavior | | ----- | -------- | | null or omitted | Phase continues indefini…
Subscription-Cycle-Trial
boolean
Indicates whether this billing cycle occurs during the subscription's trial period. This value is automatically calculated by the system based on the cycle's t…
Subscription-Plan-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 execute…
Cycle-Number
integer
The sequential cycle number within the subscription. Starts at 1 for the first cycle and increments with each new billing cycle.
Subscription-External-Reference
string
Optional external reference for the subscription. Use this field to store your own system's identifier for easy tracking and correlation.
Subscription-Items
array
A list of subscription items for this phase.
Subscription-Cycles
object
2 properties 1 required
Subscription-Usage-Date
string
The timestamp indicating when the consumption actually occurred. | Constraint | Detail | | ---------- | ------ | | Format | [ISO 8601](https://en.wikipedia.org…
Customer-Id
string
Unique identifier for the customer.
Cycle-Duration
string
The length of each billing cycle for this phase in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO8601Durations). This determines how often the cu…
Next-Page-Token
string
Token for retrieving the next page of results. Use this token as the value of the pagetoken query parameter in your next request to retrieve the next page. If…
Subscription-Item-Package-Size
number
The number of units grouped together as a single billable package. Used to enable pricing of items that are too inexpensive to charge individually. For example…
Subscription-Usages
object
2 properties
Order-Id
string
Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
Subscription-Plan-Id
string
Unique identifier for the subscription plan.
Subscription-Trial-Duration
string
The trial period duration for this subscription in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO8601Durations) (e.g., "P14D" for 14 days). Overr…
Subscription-Start-Date
string
The date and time the subscription started in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. This field is null until the subscription becomes activ…
Subscription-Item-Creation
object
A subscription item for a plan phase. Can be either a fixed-fee (flat) item or a metered (usage) item.
Subscription-Plan-Created
string
The date and time the subscription plan was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscriptions
object
2 properties 1 required
Subscription-Updated
string
The date and time the subscription was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscription-Plan-Variation-Creation
object
1 property 1 required
Subscription-Plan
object
7 properties 6 required
Currency
string
[ISO 4217](https://en.wikipedia.org/wiki/ISO4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](…
Subscription-Trial-End-Date
string
The date and time when the subscription's trial period ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. This value is automatically calculated…
Subscription-Change-Plan
object
4 properties 2 required
Subscription-Scheduled-Action
object
A pending scheduled action on the subscription, applied at the end of the current billing cycle.
Previous-Cycle-Id
string
The unique identifier of the previous billing cycle. This field is null for the first cycle in a subscription.
Subscription-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…
Subscription-Plan-State
string
The state of the subscription plan. | State | Description | | ----- | ----------- | | active | The plan is active and can be used to create new subscriptions.…
Subscription-Item-Usage-Creation
object
Object structure for usage subscription item.
9 properties 6 required
Subscription-Item-Flat-Creation
object
Object structure of flat subscription item.
7 properties 6 required
Subscription-Item-Type
string
The type of subscription item.
Subscription-Usage-Creation
object
5 properties 4 required
Subscription-Item-Code
string
A merchant-defined identifier for a usage-based subscription item. You set this code on each usage item when creating a subscription plan, and supply it when r…
Subscription-Scheduled-Action-Type
string
The type of the scheduled action. | Value | Description | | ----- | ----------- | | cancel | A cancellation scheduled to take effect at the end of the current…
Payment-Method-Id
string
Unique identifier for the payment method.
Subscription-Cycle-Usage-Cutoff-Date
string
The deadline for submitting or correcting usage records for this cycle, in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. Set to 12 hours after the…
Subscription-Item-Name
string
The name of the subscription item.
Subscription-Payment-Method-Type
string
The type of payment method used for the subscription. | Type | Description | | ---- | ----------- | | automatic | Payments are automatically charged to the cus…
Subscription-Plan-Creation
object
3 properties 2 required
Subscription-Plan-Phase
object
7 properties 3 required
Subscription-Cycle
object
13 properties 5 required
Subscription-Plan-Trial-Duration
string
The default trial period duration for this subscription plan in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO8601Durations) (e.g., "P14D" for 14…
Subscription-Cycle-Post-Billing-Order-Id
string
The ID of the order created after the cycle's usagecutoffdate to charge usage-based items accumulated during the cycle. | Scenario | Detail | | -------- | ----…
Subscription-Update
object
1 property
Subscription-Created
string
The date and time the subscription was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscription-Usage-Id
string
The unique identifier of the usage record.
Subscription-Cycle-Id
string
Unique identifier for the subscription cycle.
Subscription-Plan-Variation-Id
string
Unique identifier for the subscription plan variation.
Subscription-Cycle-End-Date
string
The date and time the subscription cycle ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscription-Item
object
A subscription item that defines a billing line within a plan phase. Can be either a fixed-fee (flat) item or a metered (usage) item.
Subscription-Creation
object
5 properties 2 required
Subscription-Id
string
Unique identifier for the subscription.
Subscription-Change-Plan-Reason
string
The reason for the scheduled action. This field is informational and does not affect how the action is processed. | Value | Description | | ----- | -----------…
Subscription-Scheduled-Action-Change-Plan
object
A plan variation change scheduled to take effect at the end of the current billing cycle.
4 properties 3 required
Subscription-Item-Usage
object
Object structure of usage subscription item.
10 properties 7 required
Subscription-Cycle-Start-Date
string
The date and time the subscription cycle starts in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Error-v2
object
3 properties
Subscription-State
string
The state of the subscription. | State | Description | | ----- | ----------- | | pending | The subscription has been created but is not yet active. This typica…
Subscription-Usage-Metadata
object
Key-value pairs you can attach to a usage record for your own tracking and reporting purposes. | Constraint | Detail | | ---------- | ------ | | Keys | Maximum…
Subscription-Item-Unit
string
The unit of measurement for the item.
Subscription-Plan-Variation
object
2 properties 2 required
Subscription-Usage-Updated-Date
string
The date and time the usage record was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscription-Item-Id
string
The unique identifier of the subscription item.
Subscription-Usage-Created-Date
string
The date and time the usage record was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Subscription-Plan-Phase-Creation
object
6 properties 4 required
Subscription-Item-Flat
object
Object structure of flat subscription item.
8 properties 7 required
Subscription-Cycle-State
string
The state of the subscription cycle. | State | Description | | ----- | ----------- | | pending | The cycle has been created but has not yet started. A cycle ca…
Subscription-Plan-Phase-Id
string
Unique identifier for the subscription plan phase.
Subscription-Usage
object
9 properties 8 required
Setup-Order-Redirect-URL
string
The URL to which the customer is redirected after completing the setup order on the Revolut Hosted Payment Page. When provided, the response will include a set…
Subscription-Plans
object
2 properties 1 required
Subscription-Plan-Updated
string
The date and time the subscription plan was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format.
Usage-Aggregation-Method
string
The method used to aggregate usage events over a billing cycle to calculate the chargeable amount. | Value | Behaviour | | ----- | --------- | | sum | Totals a…
Subscription-Plan-Name
string
The name of the subscription plan.
Subscription-Item-Quantity
number
The quantity of the item.

Specification

The full machine-readable OpenAPI contract behind this narrative.

Source

revolut-subscriptions-api-openapi.yml Raw ↑

Other APIs Revolut publishes across the network.

Revolut Accounting API
Revolut Accounting categories API
Revolut Accounts API
Revolut Apple Pay merchant registration API
Revolut Applications API
Revolut Balance API
Revolut Card invitations API
Revolut Cards API
Revolut Configuration API
Revolut Counterparties API
Revolut Customers API
Revolut Disputes API