Revolut Orders API
The Orders resource in the Merchant API offers a comprehensive solution for managing the lifecycle of orders within your e-commerce or retail platform. Designed to streamline order processing, this resource encapsulates a suite of operations that allow for efficiently handling order management-related tasks. For more information about the order lifecycle, see: [Order and payment lifecycle](https://developer.revolut.com/docs/guides/merchant/reference/order-lifecycle).These operations are equipped to handle various order management scenarios, providing a robust interface for businesses to interact with their order data.To process a payment related to your customers' purchases, you need to create an `Order` object. Then you can use an order's unique `token` to process and accept payments via the Revolut Checkout Widget.:::warningThe [Create an order endpoint](https://developer.revolut.com/docs/api/merchant#create-order) was updated to a new version and now returns `token` as the public identifier for the order. Previous integrations might still use the deprecated endpoint returning `public_id`.We strongly advise upgrading to the new [Create an order endpoint](https://developer.revolut.com/docs/api/merchant#create-order).:::
Revolut Orders API is one of 46 APIs that Revolut publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Orders. The published artifact set on APIs.io includes an OpenAPI specification.
This API exposes 18 operations across 12 paths, and defines 158 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.
18 operations
12 paths
158 schemas
2 DELETE7 GET1 PATCH7 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
Revolut Orders 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 18
Across 12 paths, the API surfaces 18 operations — 2 DELETE, 7 GET, 1 PATCH, 7 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
Orders 18
The Orders resource in the Merchant API offers a comprehensive solution for managing the lifecycle of orders within your e-commerce or retail platform. Designed to streamline orde…
POST
/api/orders
Create an order
GET
/api/orders
Retrieve an order list
GET
/api/orders/{order_id}
Retrieve an order
PATCH
/api/orders/{order_id}
Update an order
POST
/api/orders/{order_id}/increment-authorisation
Increment authorisation
POST
/api/orders/{order_id}/capture
Capture an order
POST
/api/orders/{order_id}/cancel
Cancel an order
POST
/api/orders/{order_id}/refund
Refund an order
POST
/api/orders/{order_id}/payments
Pay for an order
GET
/api/orders/{order_id}/payments
Retrieve payment list of an order
POST
/orders
Place order
DELETE
/orders
Cancel all active orders
GET
/orders/active
Get active orders
GET
/orders/historical
Get historical orders
GET
/orders/{venue_order_id}
Get order by ID
DELETE
/orders/{venue_order_id}
Cancel order by ID
PUT
/orders/{venue_order_id}
Replace order
GET
/orders/fills/{venue_order_id}
Get fills of order by ID
Schemas 158
The contract defines 158 schemas that model the data the API accepts and returns. The most detailed are Order-v7 (31 properties), OrderDetails (26 properties), Order-Simplified-v2 (23 properties), Order (22 properties). Each schema is shown below with its type and property counts.
Payment-Retrieval
object
9 properties
3 required
Full-Name
string
The full name of the customer.
Merchant-Order-Url
string
The URL of the order stored in the merchant's order management system. This URL will be included in the order confirmation email for payments made via Revolut…
Marketplace-v3
object
This object is required by Mastercard and Visa for merchants operating as marketplaces under the Merchant Category Code (MCC) 5262. The marketplace object ensu…
1 property
1 required
Revolut-Pay-Account
object
3 properties
1 required
Sepa-Direct-Debit
object
Object containing details of a SEPA Direct Debit payment. :::info For more information, see: [SEPA Direct Debit server-to-server integration](https://developer…
5 properties
1 required
Customer-v2
object
Object containing information about a customer. If you have it, we strongly advise providing at least either id, phone, or email. Using the [Customers operatio…
5 properties
Card-Checks-v2
object
The details of the check for card payment. Only for orders with successful payments.
5 properties
Payment-Updated
string
The date and time the payment was last updated.
Decline-Reason-v2
string
The reason for a failed or declined payment. A failed or declined payment can result from multiple reasons. To learn more, check our [failure reasons](https://…
OrderReplacementRequest
object
Request to replace an existing open order with a new one, atomically cancelling the original. Only the fields provided in the request are updated; omitted fiel…
6 properties
1 required
Three-Ds-Fingerprint
object
Information about the 3DS fingerprint challenge.
3 properties
3 required
Payment-Risk-Level
string
The risk level of the card. If the risk level is high, the payment might be declined.
MarketOrderConfiguration
object
Market order configuration. Must contain exactly one of 'basesize' or 'quotesize'.
2 properties
Fees
array
The details of the order fee.
Order-Creation-v7
object
Object schema containing information about order creation body request parameters.
19 properties
2 required
Lodging-Category
string
The type of the accommodation associated with the booking.
Journey-Legs
array
Array containing information of journey legs associated with the booking. :::info This field is required for activating Revolut Flight Alerts functionalities w…
Lodging-Location
object
Address of the accommodation.
6 properties
4 required
Apple-Pay
object
Object containing details of a card used via Apple Pay.
16 properties
1 required
Outstanding-Amount
integer
The amount not yet paid for a given order (in minor currency units). For example, 7034 represents €70.34. The value in this field may differ from amount if the…
Event
object
Object containing booking information about a specific event.
9 properties
Payment-Authorised-Amount
integer
The currently authorised amount for this payment (in minor units). For pre-authorised payments with incremental authorization: - Initially equals the amount fi…
Customer-Id
string
Unique identifier for the customer.
Payment-Created
string
The date and time the payment was created.
Refundability
string
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Passenger
object
2 properties
2 required
Incremental-Authorisation-Request
object
3 properties
1 required
Order-Id
string
Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
RPay-Account
object
3 properties
2 required
Capture-Deadline
string
The date and time by which the payment must be captured. After this deadline, the authorised funds may be automatically released by the card issuer.
Guests
array
List of guests associated with the booking.
Date-Of-Birth
string
The birth date of the customer.
Payment-Settled-Amount
integer
The amount of the settled payment (minor currency unit). For example, 7034 stands for €70.34.
Order-v7
object
To process the order from a credit or debit card, you create an Order object. You can then retrieve, capture, cancel, refund, or pay an order using its unique…
31 properties
Incremental-Authorisation
object
Represents a single incremental authorisation attempt on an order. The incrementalauthorisations array tracks all increment attempts (successful and failed) in…
6 properties
Lodging-Check-Out-Date
string
[ISO 8601](https://en.wikipedia.org/wiki/ISO8601) date and time of the check-out.
Expire-Pending-After
string
Automatic expiration period for pending orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. Orders in pending state will be automati…
Related-Order-Id
string
The unique ID of the original order that was refunded and this refund is associated with. You can use this ID to get more information about the related order u…
Incremental-Authorisations
array
History of incremental authorisation attempts for this order. Only present for orders with authorisationtype: preauthorisation. Contains all increment attempts…
Card
object
Object containing details of the card used for the payment.
16 properties
1 required
Order-Refund-v2
object
The request body for creating a refund order.
5 properties
2 required
Increment-Reference
string
External reference for this incremental authorisation. :::tip Use your internal charge or invoice ID. This reference is returned in webhooks for easy matching…
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](…
Crypto-Transaction
object
4 properties
3 required
Shipments
array
List of individual shipment details.
Environment
object
Environment object, indicating in which environment the payment was made. :::warning Only required if initiator: customer. ::: :::note Only browser is availabl…
Card-For-Payment-Details
object
4 properties
1 required
RPay-Card
object
5 properties
2 required
Email
string
The email address of the customer.
Cancel-Authorised-After
string
Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. After this period, the authorised p…
Redirect-Url
string
The URL your customer will be redirected to after a successful payment on the hosted checkout page (checkouturl parameter's value of the order). :::warning Res…
OrderReplacementResponse
object
1 property
1 required
Address-v3
object
Details of a physical address.
6 properties
4 required
Revolut-Pay-Card
object
Object containing details of a card used via Revolut Pay.
16 properties
1 required
Upcoming-Payment
object
Object containing information about upcoming payments associated with the order.
2 properties
2 required
Fee
object
3 properties
Shipment
object
Details of an individual shipment.
4 properties
2 required
ActiveOrdersPaginatedResponse
object
2 properties
2 required
Tax
object
Details about a tax applied to the line item, including its name and the corresponding amount.
2 properties
2 required
Lodging-Booking-Type
string
Indicates whether the booking terms are fixed or flexible. | Parameter value | Description | | --------------- | ----------- | | fixed | Non-modifiable once co…
Order-Token
string
Temporary ID for the order, which expires when the payment is authorised. The order token is used for [token-based initialisation](https://developer.revolut.co…
Guest
object
2 properties
2 required
Order-Capture-v2
object
Order capture request parameters. You can optionally provide line items when capturing an order. This is useful when you need to adjust the final order details…
2 properties
Payment-Id
string
The ID of the payment.
Payment-State-v2
string
The status of the payment.
Events-v2
object
Object containing booking information for a list of event tickets associated with the order. :::info These are the specific data field requirements for merchan…
2 properties
1 required
Order-Update-v7
object
Object schema containing information about order update body request parameters.
17 properties
Refund-Amount
integer
The amount to be refunded, specified in the smallest currency unit (e.g., cents for USD, pence for GBP).
ExecutionInstructions
array
List of execution instructions for the order. Can be provided as an empty array [] if no specific instructions are required.
OrderPlacementRequest
object
4 properties
4 required
Terminal-Hardware-Id
string
The hardware identifier of the Revolut Terminal device used to process the payment. :::note Only present for card-present transactions processed via Revolut Te…
Three-Ds-Fingerprint-v2
object
Information about the 3DS fingerprint challenge.
2 properties
2 required
Lodging-v3
object
Object containing details of a lodging booking. :::info These are the specific data field requirements for merchants who must provide lodging data. Note that t…
2 properties
1 required
Revolut-Pay
Authentication-Challenge-Type
string
Type of the authentication challenge the payment triggers.
Google-Pay
object
Object containing details of a card used via Google Pay.
16 properties
1 required
Order-Customer-v2
object
A lightweight customer object embedded in an order. This is a simplified representation intended for the order context. For the full customer object including…
5 properties
1 required
Subscription-Active-Cycle-Id
string
The unique identifier of the active (pre-paid) subscription cycle that this order collects payment for. This is the current billing cycle whose recurring charg…
Authorisation-Type
string
The type of authorisation for the order. Used with manual capture mode. If omitted, final is used by default. Pre-authorisation Pre-authorisation allows you to…
Crypto-Transactions-v3
object
Object containing information about crypto transactions associated with the order. :::info Processing crypto on-ramp transactions with Revolut has additional c…
2 properties
1 required
Subscription-Settled-Cycle-Id
string
The unique identifier of the settled (post-paid) subscription cycle whose usage-based charges this order collects. This is the previous billing cycle whose usa…
Order-Capture-Amount
integer
Specify an amount to capture, in minor currency units. The amount must not exceed the authorised amount. An order can only be captured once. Partial capture is…
Payment-v3
object
Represents a payment for an order. For pre-authorised payments, the authorisedamount field tracks the currently authorised amount, which may differ from amount…
18 properties
5 required
Capture-Mode-v2
string
The capture mode of the order. automatic is used by default. | Parameter value | Description | | --------------- | ----------- | | automatic | The order is cap…
Subscription-Data
object
Subscription details linked to the order. Use this object to match an order with its underlying subscription and understand the billing context in which the or…
4 properties
2 required
Metadata
object
Additional information to track your orders in your system, by providing custom metadata using " " : " " pairs. :::warning Restrictions: - Both keys and values…
Car-Rental-v2
object
Object containing additional information about a car rental booking associated with the order. :::info These are the specific data field requirements for merch…
7 properties
2 required
Network-Transaction-Id
string
The Network Transaction ID (NTI) is a unique identifier assigned by the card scheme (e.g., Visa or Mastercard) to a card transaction. It can be used to trace t…
LimitOrderConfiguration
object
5 properties
1 required
OnFill
object
Details of the Take Profit/Stop Loss exit strategy order linked to the current order. The linked TPSL order will be submitted once the current order is filled.
3 properties
Statement-Descriptor-Suffix
string
You can set a dynamic statement descriptor for your orders by providing a custom suffix. A statement descriptor is the text shown on cardholders' bank or card…
Line-Items
array
An array of line items included in the order. Each line item represents an individual product or service, along with its quantity, price, taxes, and discounts.…
Fingerprint
string
A unique identifier for a payment method, always 44 characters long. This fingerprint can be used to uniquely identify various payment methods. Fingerprint gen…
Authentication-Challenge
object
Details about the authentication challenge that should be performed to complete the authentication process. For more information about Revolut's 3DS solution,…
Order-Type-v2
string
The type of the order.
Checkout-Url
string
Link to a checkout page hosted by Revolut.
Lodging-Check-In-Date
string
[ISO 8601](https://en.wikipedia.org/wiki/ISO8601) date and time of the check-in.
ErrorResponse
object
Standard error response structure
3 properties
3 required
Orders-v2
object
1 property
1 required
Airline-Data-v2
object
Object containing additional information about an airline booking associated with the order. Use this object to provide required data to enable Revolut Flight…
10 properties
1 required
Passengers
array
Array containing information of passengers associated with the booking.
Merchant-Order-External-Reference
string
Merchant order ID for external reference. Use this field to set the ID that your own system can use to easily track orders.
Side
string
The direction of the order.
Payment-Method-v2
object
The details of the payment method used to make the payment.
Lodging-Item
object
Object containing details of an individual lodging entry.
8 properties
Enforce-Challenge-v2
string
The enforce challenge mode. automatic is used by default. | Parameter value | Description | | --------------- | ----------- | | automatic | The payments create…
Image-Url
string
URL to an image associated with the line item. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rf…
Three-Ds
object
Information about the 3DS challenge.
2 properties
2 required
Order-Description
string
The description of the order.
Merchant-Order-Data
object
Object for providing additional information stored in the merchant's order management system.
2 properties
Order-State
string
The state of the order in its lifecycle. | State | Description | |-------|-------------| | pending | Order created, awaiting payment | | processing | Payment i…
OrderDetails
object
The requested order details.
26 properties
14 required
Contact
object
Contact details for someone responsible for the shipment. :::warning At least email or phone is required. :::
3 properties
Order-Amount-v2
integer
The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO4217). For example, 7034 in EUR corres…
Subscription-Id
string
Unique identifier for the subscription.
Arn
string
Acquirer Reference Number (ARN) of the payment. :::note Only returned for refund payments made by a card. :::
Location-Id
string
Unique ID representing the location where merchants sells products. :::info For more information, see: [Locations](https://developer.revolut.com/docs/api/merch…
Discount
object
Details of a discount applied to the line item, including its name and monetary value.
2 properties
2 required
Cancel-Authorised-After-v2
string
Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format. After this period, the authorised p…
Supplier-Payment-Date
string
[ISO 8601](https://en.wikipedia.org/wiki/ISO8601) date and time when the funds are released to merchants.
Phone
string
The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164).
Refunded-Amount
integer
The amount that was refunded from the order (in minor currency units). For example, 7034 represents €70.34. This applies to orders that have been refunded (i.e…
TriggeredBy
object
Details of the trigger order that submitted the current order. The current order was created when the trigger condition of a parent conditional or Take Profit/…
4 properties
OrderTrigger
object
6 properties
5 required
Settlement-Currency
string
[ISO 4217](https://en.wikipedia.org/wiki/ISO4217) currency code in upper case. If settlementcurrency is different from the value of currency, the money will be…
Address-v4
object
Details of a physical address.
7 properties
4 required
Subscription-Order-Billing-Reason
string
The reason this subscription order was created. | Value | Description | | ----- | ----------- | | cyclebilling | The order was automatically generated to colle…
Industry-Data-v3
object
Object containing industry-specific information associated with the order. You can provide data for one or multiple industries in a single order. :::info In th…
6 properties
Sepa-Direct-Debit-Debtor-Name
string
The full name of the debtor as provided in the mandate.
Sepa-Direct-Debit-Debtor-Iban-Last-Four
string
The last four digits of the debtor's IBAN.
Payer
object
The person who made the payment. This object is present when an email or phone number is provided during the payment flow. Capturing payer details lets you ide…
2 properties
Increment-Amount
integer
The new total amount to be authorised (in minor units, e.g., cents). This should be the full new amount, not the increment value. For example, if the current a…
Refund-Currency
string
[ISO 4217](https://en.wikipedia.org/wiki/ISO4217) currency code in upper case. Must match the currency of the original order to be refunded. :::info For more i…
ClientTrade
object
A single trade.
16 properties
15 required
Error-v2
object
3 properties
Payment-Method-Type
string
The type of payment method used to pay for the order. Available values: | Payment method type | Description | | --------------------- | ----------- | | applepa…
Payment-Settled-Currency
string
The currency of the settled payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO4217) currency code in upper case. :::info For more information about the supp…
Authentication-Challenge-v2
object
Details about the authentication challenge that should be performed to complete the authentication process. For more information about Revolut's 3DS solution,…
Address-v2
object
Object containing address details.
6 properties
2 required
Ticket
object
Object containing information about a ticket associated with the booking.
3 properties
1 required
Quantity
object
Object representing the quantity details of a line item, including the amount and its associated unit of measurement.
2 properties
1 required
Order-Simplified-v2
object
A simplified order object returned in list responses. To get the full details of an order, use the [Retrieve an order](https://developer.revolut.com/docs/api/m…
23 properties
10 required
Order
object
22 properties
14 required
OrderPlacementResponse
object
1 property
1 required
Payment-Token
string
Temporary token of the payment used to fetch the reward offer during checkout and link user registrations to the given offers. The token is only valid for a li…
Saved-Payment-Method
object
1 property
1 required
Authorisation-Code
string
The authorisation code (or auth code) is a short, alphanumeric code returned by the cardholder's issuing bank to the merchant's terminal or payment gateway. It…
Sepa-Direct-Debit-Mandate-Reference
string
The unique mandate reference generated by Revolut. Include this in pre-debit notifications sent to your customers.
Browser-Environment
object
Browser environment
8 properties
6 required
Shipping
object
Details about the shipping related to the order, including address, contact information, and individual shipments. :::info Required for merchants shipping phys…
3 properties
Journey-Leg
object
9 properties
6 required
Booking-Id
string
A unique identifier provided by the merchant associated with the order. This bookingid is used to reference and correlate booking information with the Merchant…
HistoricalOrdersPaginatedResponse
object
2 properties
2 required
Payment-Amount
integer
The payment amount in minor units (e.g., cents). The value of this field depends on the payment type and state. | Payment type | State | Amount value | |------…
Lodging-Supplier
object
Object containing supplier information about the lodging provider.
3 properties
Line-Item
object
11 properties
5 required
Bank-Message
string
The reason for a failed or declined payment, sent by the financial institution processing the payment.
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Revolut 12
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
#Orders