Retrieve an order list

Get a paginated list of your orders, returned as a wrapped orders array.

The response contains simplified Order objects. To get the full details of a specific order, use the Retrieve an order endpoint.

Request

Query parameters

Possible values: >= 1 and <= 500

Default value: 100

Maximum number of records to return. Used for pagination.

Filter records created from this date/time. Used for filtering.

Filter records created until this date/time. Used for filtering.

Filter orders by the ID of the customer.

Filter orders by your own order reference set in merchant_order_data.reference.

Possible values: [pending, processing, authorised, completed, cancelled, failed]
Example: "authorised"

Filter orders by state. Repeat the parameter to filter by multiple states.

Value	Description
`pending`	Order created, awaiting payment
`processing`	Payment is being processed
`authorised`	Payment authorised but not yet captured (for manual capture)
`completed`	Payment successfully captured and settled
`cancelled`	Order was cancelled
`failed`	Payment failed

Filter results by location ID.

Header parameters

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.

Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16, 2025-12-04, 2026-03-12, 2026-04-20]
Example: "2026-04-20"

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

If not specified, you will receive an error.

Response

Response body

Body object

List of orders.

Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.

Temporary ID for the order, which expires when the payment is authorised.

The order token is used for token-based initialisation, and is returned by the createOrder callback in the following payment methods:

[Embedded Checkout](/docs/sdks/merchant-web-sdk/payment-methods/embedded-checkout#embeddedcheckout options-interface)
Revolut Pay
Apple Pay and Google Pay
Pay by Bank

Possible values: [payment, payment_request, refund, chargeback, chargeback_reversal, credit_reimbursement]

The type of the order.

Possible values: [pending, processing, authorised, completed, cancelled, failed]
Example: "authorised"

The state of the order in its lifecycle.

State	Description
`pending`	Order created, awaiting payment
`processing`	Payment is being processed
`authorised`	Payment authorised but not yet captured (for manual capture)
`completed`	Payment successfully captured and settled
`cancelled`	Order was cancelled
`failed`	Payment failed

For more information, see: Order and payment lifecycle

The date and time the order was created.

The date and time the order was last updated.

The order total expressed in minor currency units, according to the ISO 4217 standard. For example, 7034 in EUR corresponds to €70.34.

Info

Conversion between major and minor units varies by currency. For instance, 100 minor units equal £1.00 in GBP, whereas in ISK they represent 100 units. For more details, see the ISO 4217 standard.
If line_items are provided, the order amount must equal the sum of all line items' total_amount.
For card payments with a non-zero amount, the order amount must be at least $0.005 (or equivalent in different currencies, calculated using Revolut's exchange rate on the payment date). Otherwise, card payments can't be performed.

Possible length: >= 3 characters and <= 3 characters

ISO 4217 currency code in upper case.

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 there are partial payments associated with the order.

Possible values: [automatic, manual]

Default value: automatic

The capture mode of the order. automatic is used by default.

Parameter value	Description
`automatic`	The order is captured automatically after payment authorisation.
`manual`	The order is not captured automatically. You must manually capture the order later.

Possible values: [automatic, forced]

Default value: automatic

The enforce challenge mode. automatic is used by default.

Parameter value	Description
`automatic`	The payments created for an order will have challenge requirement calculated by our fraud mechanisms. Not all payments will trigger a 3DS challenge.
`forced`	The payments created for an order will always require a 3DS challenge. Currently only supported for card payments.

Possible values: [final, pre_authorisation]

Default value: final

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 reserve funds on a customer's card without immediately capturing them. This is useful for scenarios like:

Hotel bookings where the final amount may vary
Car rentals where additional charges may apply
Deposits that need to be held temporarily

Parameter value	Description
`final`	Standard authorisation for immediate or near-immediate capture.
`pre_authorisation`	Reserve funds for later capture, used with manual capture mode.

The description of the order.

Example:

{
  "order_reference": "ORD-12345",
  "customer_segment": "premium",
  "internal_note": "VIP customer - priority handling"
}

Property count: <= 50 properties

Additional information to track your orders in your system, by providing custom metadata using "<key>" : "<value>" pairs.

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 using the Retrieve an order operation.

A lightweight customer object embedded in an order.

This is a simplified representation intended for the order context. For the full customer object including all payment methods, use the Retrieve a customer endpoint.

Possible number of items: <= 250 items

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.

Possible length: <= 250 characters

Name of the line item.

Possible values: [physical, service]

Type of the line item.

Object representing the quantity details of a line item, including the amount and its associated unit of measurement.

The unit price of the line item.

The total amount to be paid for the line item, including taxes and discounts.

Possible length: <= 250 characters

Unique identifier of line item in the merchant's system.

Possible number of items: <= 50 items

A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item.

Possible number of items: <= 50 items

A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item.

Possible number of items: <= 50 items

A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item.

Possible length: <= 1024 characters

Description of the line item.

Possible length: <= 2000 characters
Pattern: Value must match regular expression ^https?:\/{2}.+/gi

An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details.

Object for providing additional information stored in the merchant's order management system.

Possible length: <= 2000 characters
Pattern: Value must match regular expression ^https?:\/{2}.+/gi

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 Pay. If specified, this URL will override the default link to the merchant's Business website configured in the Revolut Business account.

Merchant order ID for external reference.

Use this field to set the ID that your own system can use to easily track orders.

Unique ID representing the location where merchants sells products.

Possible length: <= 2000 characters
Pattern: Value must match regular expression ^https?:\/{2}.+/gi

The URL your customer will be redirected to after a successful payment on the hosted checkout page (checkout_url parameter's value of the order).

Automatic cancellation period for uncaptured orders, specified in ISO 8601 format.

After this period, the authorised payment is automatically cancelled and the order is cancelled. Maximum: 7 days = P7D.

Note

The following limitations apply:

Cannot be a negative value.
Cannot be updated if the new value is less than or equal to the elapsed time since authorisation.

Failing scenario:
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 2 days
In this scenario, an error is returned.

Successful scenario:
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 4 days
In this scenario, the parameter can be updated.
Cannot be updated if cancellation is ≤ 30 minutes away.

Failing scenario:
- Original value: 12 hours
- Time since authorisation: 11 hours 40 minutes
In this scenario, an error is returned.

Successful scenario:
- Original value: 12 hours
- Time since authorisation: 11 hours 20 minutes
In this scenario, the parameter can be updated.

Possible length: non-empty and <= 19 characters
Pattern: Value must match regular expression ^[^*\n\r\\]+$

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 statements, helping them recognise a transaction or merchant. This field can be used to send extra information with the statement descriptor for card transactions.

The complete descriptor is built using the following format: {base}*{suffix}, where:

{base} is the existing descriptor configured in the Revolut Business dashboard (Settings > Business account > Merchant profile > Statement descriptor).
{suffix} is defined by the statement_descriptor_suffix field.

Retrieve an order list

Request​

Response​

Pre-authorisation

Request

Response