--- api: 'Merchant API' --- # 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](/docs/api/merchant#retrieve-an-order) endpoint. ## Endpoint GET `/api/orders` ## Parameters ### query parameters - `limit` (integer, optional) Maximum number of records to return. Used for **pagination**. - `from` (string, optional) Filter records created from this date/time. Used for **filtering**. - `to` (string, optional) Filter records created until this date/time. Used for **filtering**. - `customer_id` (string, optional) Filter orders by the ID of the customer. - `merchant_order_data_reference` (string, optional) Filter orders by your own order reference set in `merchant_order_data.reference`. - `state` (array of enum, optional) 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 | - `location_id` (string, optional) Filter results by location ID. ## Returns ### 200 OK #### Response attributes - `orders` (array of object) List of orders. - `orders[].id` (string) Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization. - `orders[].token` (string, optional) Temporary ID for the order, which expires when the payment is authorised. The order `token` is used for [token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based), 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](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay#widgetpaymentsrevolutpayoptions) - [Apple Pay and Google Pay](/docs/sdks/merchant-web-sdk/payment-methods/apple-pay-google-pay#paymentrequestoptions-interface) - [Pay by Bank](/docs/sdks/merchant-web-sdk/payment-methods/pay-by-bank#paybybankoptions-interface) - `orders[].type` (enum) The type of the order. Possible enum values: - `payment` - `payment_request` - `refund` - `chargeback` - `chargeback_reversal` - `credit_reimbursement` - `orders[].state` (enum) 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](/docs/guides/merchant/reference/order-lifecycle) Possible enum values: - `pending` - `processing` - `authorised` - `completed` - `cancelled` - `failed` - `orders[].created_at` (string) The date and time the order was created. - `orders[].updated_at` (string) The date and time the order was last updated. - `orders[].amount` (integer) The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). 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](https://en.wikipedia.org/wiki/ISO_4217). - 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. ::: - `orders[].currency` (string) [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: - `orders[].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 there are partial payments associated with the order. - `orders[].capture_mode` (enum) 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. | :::info For more information, see [Capture an order](/docs/api/merchant#capture-an-order). ::: Possible enum values: - `automatic` - `manual` - `orders[].enforce_challenge` (enum) 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 enum values: - `automatic` - `forced` - `orders[].authorisation_type` (enum, optional) 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. | :::note Pre-authorisation must be used with `capture_mode: manual`. For more information, see [Capture an order](/docs/api/merchant#capture-an-order). ::: Possible enum values: - `final` - `pre_authorisation` - `orders[].description` (string, optional) The description of the order. - `orders[].metadata` (object, optional) Additional information to track your orders in your system, by providing custom metadata using `"" : ""` pairs. :::warning **Restrictions:** - Both keys and values must be `string`s - Values cannot be `null`. - Max number of key-value pairs: `50` - Max length of values: `500` characters - Format of keys: Must start with a letter and contain only letters, digits, and underscores. Max 40 characters. Pattern: `^[a-zA-Z][a-zA-Z\\d_]{0,39}$` ::: - `orders[].related_order_id` (string, optional) 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](/docs/api/merchant#retrieve-an-order) operation. :::note This field is only returned for orders with `type: refund`. ::: - `orders[].customer` (object, optional) 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](/docs/api/merchant#retrieve-a-customer) endpoint. - `orders[].customer.id` (string) Unique identifier for the customer. - `orders[].customer.email` (string, optional) The email address of the customer. - `orders[].customer.phone` (string, optional) The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). - `orders[].customer.full_name` (string, optional) The full name of the customer. - `orders[].customer.date_of_birth` (string, optional) The birth date of the customer. - `orders[].line_items` (array of object, optional) 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. :::info Required for merchants collecting payment for one or multiple products/services in one transaction. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut. ::: - `orders[].line_items[].name` (string) Name of the line item. - `orders[].line_items[].type` (enum) Type of the line item. Possible enum values: - `physical` - `service` - `orders[].line_items[].quantity` (object) Object representing the quantity details of a line item, including the amount and its associated unit of measurement. - `orders[].line_items[].quantity.value` (number) The number of units of the line item. - `orders[].line_items[].quantity.unit` (string, optional) The measurement unit for the quantity, such as `cm`, or `kg`. - `orders[].line_items[].unit_price_amount` (integer) The unit price of the line item. - `orders[].line_items[].total_amount` (integer) The total amount to be paid for the line item, including taxes and discounts. - `orders[].line_items[].external_id` (string, optional) Unique identifier of line item in the merchant's system. - `orders[].line_items[].discounts` (array of object, optional) A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item. - `orders[].line_items[].discounts[].name` (string) The specific name or label of the discount applied to the line item. - `orders[].line_items[].discounts[].amount` (integer) The monetary value of the discount. - `orders[].line_items[].taxes` (array of object, optional) A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item. - `orders[].line_items[].taxes[].name` (string) The specific name or designation of the tax applied to the line item. - `orders[].line_items[].taxes[].amount` (integer) The monetary value of the tax in minor currency units (e.g., cents for EUR). - `orders[].line_items[].image_urls` (array of string, optional) A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item. - `orders[].line_items[].description` (string, optional) Description of the line item. - `orders[].line_items[].url` (string, optional) An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: - `orders[].merchant_order_data` (object, optional) Object for providing additional information stored in the merchant's order management system. - `orders[].merchant_order_data.url` (string, optional) 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. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: - `orders[].merchant_order_data.reference` (string, optional) Merchant order ID for external reference. Use this field to set the ID that your own system can use to easily track orders. - `orders[].location_id` (string, optional) Unique ID representing the location where merchants sells products. :::info For more information, see: [Locations](/docs/api/merchant#tag-locations). ::: - `orders[].redirect_url` (string, optional) 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). :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: :::info For more information on how to use the `redirect_url`, see: [Custom redirection via the API](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/api#custom-post-payment-redirection-optional) ::: - `orders[].cancel_authorised_after` (string, optional) Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/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. ::: - `orders[].statement_descriptor_suffix` (string, optional) 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. :::note - If the combined descriptor's length (base + suffix) exceeds the character limits of card scheme providers, the final value will be truncated. For example if the limit is 22 characters, the base descriptor is `"base"` and the suffix is `"testdescriptorsuffix"`, the final descriptor becomes `"base*testdescriptorsuf"`. - The final statement descriptor shown on a cardholder's statement may vary by issuing bank, as some banks apply their own custom formatting or truncation rules. ::: ## Error responses | HTTP status code | Description | | --- | --- | | 400 | Bad Request | | 401 | Unauthorized |