Create a subscription

Create a new subscription for a customer using a subscription plan variation.

There are several supported flows for creating and activating subscriptions, depending on your integration needs.

Note

The customer must already exist in the API. The customer_id is required for all subscription flows.

Flow 1: Hosted Payment Page (HPP)​

Use this flow to redirect the customer to Revolut's Hosted Payment Page to complete the first payment and save their payment method.

Backend flow:

1. Create a subscription with optional setup_order_redirect_url:
   • If provided: The setup order's redirect_url field will be set to this value.
   • If omitted: The setup order will use Revolut's default redirect behavior.
2. The subscription is created in a pending state with a setup_order_id in the response.
3. Retrieve the order using setup_order_id as the order_id in the path to get the checkout_url.
4. Redirect the customer to the checkout_url for the Hosted Payment Page.

Customer flow:

1. Customer is redirected to Revolut's Hosted Payment Page.
2. Customer completes payment on the HPP, and their payment method is saved.
3. Customer redirect after payment depends on your setup:
   • With setup_order_redirect_url: Customer is redirected to your custom URL.
   • Without setup_order_redirect_url: Customer sees the default Revolut completion screen.

Key characteristics:

• Customer completes payment on Revolut's hosted page
• Payment method is automatically saved for future billing cycles
• Optional custom redirect after payment
• Best for web-based integrations

Flow 2: Widget or card-not-present (CNP) payment​

Use this flow when you want to embed the payment experience directly on your website using one of Revolut's payment widgets or handle card-not-present payments.

Backend flow:

1. Create a subscription with minimal required parameters.
2. The subscription is created in a pending state with a setup_order_id in the response.
3. Retrieve the order using setup_order_id as the order_id in the path to get order details for your integration.
4. Integrate your payment solution (widget, SDK, or CNP method) on your frontend, ensuring it's configured to save the customer's payment method for recurring billing.

Customer flow:

1. Customer stays on your website/application.
2. Customer completes payment, and their payment method is saved for future billing cycles.

Key characteristics:

• Payment experience embedded directly in your application
• Customer never leaves your website
• Payment method is saved for future billing cycles
• Best for native mobile apps or fully custom web experiences

Request​

Header parameters

Header parameters

The Idempotency-Key ensures that requests are processed only once, preventing multiple executions of the same operation due to retries or duplicate requests.

This header is optional and can accept any unique string value the merchant uses.

A recommended practice is to use a unique identifier from your system (such as the entity's ID or a request UUID) as the idempotency key. This facilitates tracking and managing requests effectively.

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

Info

For more information, see: Authentication

Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16]
Example: "2025-10-16"

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

Info

For more information about API versioning, see: API versions.

Request body

Body object

Unique identifier for the subscription plan variation.

Unique identifier for the customer.

Possible length: <= 1024 characters

Optional external reference for the subscription.

Use this field to store your own system's identifier for easy tracking and correlation.

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 setup_order_id. Use the Retrieve an order endpoint with this setup_order_id to get the checkout_url for redirecting the customer to the Hosted Payment Page.

Response​

Subscription created successfully

Response body

Body object

Unique identifier for the subscription.

Possible length: <= 1024 characters

Optional external reference for the subscription.

Use this field to store your own system's identifier for easy tracking and correlation.

Possible values: [pending, active, overdue, paused, cancelled, finished]

The state of the subscription.

State	Description
pending	The subscription has been created but is not yet active. This typically occurs when awaiting the first payment or setup completion.
active	The subscription is currently active and billing cycles are processing normally.
overdue	The subscription has a failed payment and is awaiting resolution.
paused	The subscription has been temporarily paused and no billing will occur.
cancelled	The subscription has been cancelled and will not renew.
finished	The subscription has completed all billing cycles (for limited-duration subscriptions).

Unique identifier for the customer.

Unique identifier for the subscription plan.

Unique identifier for the subscription plan variation.

Possible values: [automatic, manual]

The type of payment method used for the subscription.

Type	Description
automatic	Payments are automatically charged to the customer's saved payment method.
manual	Payments require manual processing by the customer.

Unique identifier for the payment method.

The date and time the subscription was created in ISO 8601 format.

The date and time the subscription was last updated in ISO 8601 format.

The date and time the subscription started in ISO 8601 format.

This field is null until the subscription becomes active.

Unique identifier for the subscription cycle.

The ID of the order created for handling the setup payment for the subscription.

Use the Retrieve an order endpoint with this ID to get order details, including the checkout_url for redirecting customers to the Hosted Payment Page or the token for widget integration.

Note

The order is created in parallel to the subscription and is used to collect the initial payment and save the customer's payment method for future billing cycles.