---
updatedAt: 2026-02-12T19:58:16.000Z
agentTools:
projectIndex: https://docs.withreach.com/llms.txt
---
# /query
Query information from the Reach system using an OrderId, ReferenceId, or ContractId.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "2.22",
"title": "Reach Checkout API",
"contact": {
"email": "support@withreach.com"
},
"description": "June 2022
withreach.com
docs.withreach.com
Reach's Checkout API provides suppliers the ability to execute and manage payment processing for consumer orders while retaining control over the shopper experience and limiting PCI DSS exposure. Creating payment orders, refunding payments, and querying available foreign exchange rates and payment methods are all provided by this JSON-based API.\n"
},
"servers": [
{
"description": "Reach Sandbox",
"url": "https://checkout.rch.how/v2.22"
},
{
"description": "Reach Dev",
"url": "https://checkout.rch.red/v2.22"
}
],
"paths": {
"/query": {
"post": {
"operationId": "query",
"description": "Query information from the Reach system using an OrderId, ReferenceId, or ContractId.\n",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"allOf": [
{
"type": "object",
"required": [
"request",
"signature"
],
"properties": {
"request": {
"type": "object",
"properties": {
"MerchantId": {
"description": "The 36 character GUID which identifies the supplier to the Reach system.\n",
"type": "string",
"format": "uuid"
},
"OrderId": {
"description": "The 36 character GUID which identifies the order in the Reach system.\n",
"type": "string",
"format": "uuid"
},
"ReferenceId": {
"description": "A string identifying an external reference (such as in the supplier's order management system), if one was specified in /checkout or /create.",
"type": "string",
"format": "uuid"
},
"ContractId": {
"description": "The identifier for the Reach contract, if a contract was opened using the OpenContract option in /checkout or /authorize, or through the openContract request.",
"type": "string",
"format": "uuid"
}
},
"required": [
"MerchantId"
]
},
"signature": {
"description": "Computed SHA256 HMAC value of the `request` JSON object (before any encoding) using the shared secret provided by Reach. See [Signature Calculation](https://docs.withreach.com/docs/signature-calculation) for more details.\n",
"type": "string"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Information about the queried object, the specific response depends on which parameter was used in the request. Click to see the specific response schemas.\n",
"content": {
"x-www-form-urlencoded": {
"schema": {
"oneOf": [
{
"title": "(OrderId) Information about the order.\n",
"type": "object",
"properties": {
"MerchantId": {
"description": "The 36 character GUID which identifies the supplier to the Reach system.\n",
"type": "string",
"format": "uuid"
},
"ReferenceId": {
"type": "string"
},
"OrderId": {
"description": "The 36 character GUID which identifies the order in the Reach system.\n",
"type": "string",
"format": "uuid"
},
"TransactionId": {
"description": "The identifier for the Reach payment transaction associated with the order.\n",
"type": "string",
"format": "uuid"
},
"ContractId": {
"description": "The identifier for the Reach contract, if a contract was opened using the OpenContract option in checkout or authorize, or through the openContract request.\n",
"type": "string",
"format": "uuid"
},
"RateOfferId": {
"description": "The identifier for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement.\n",
"type": "string",
"format": "uuid"
},
"Rate": {
"description": "The foreign exchange rate used for this order. If omitted, the rate will be determined at the time of settlement.\n",
"type": "number",
"format": "double"
},
"UnderReview": {
"description": "Set to true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed.\n",
"type": "boolean"
},
"Chargeback": {
"description": "Set to true if a chargeback has been issued against the order. An outstanding chargeback disables the ability to submit a refund against the order.\n",
"type": "boolean"
},
"OrderState": {
"description": "See documentation on [Order States](https://docs.withreach.com/docs/states-and-events#section-orders).\n",
"type": "string"
},
"Reason": {
"description": "A non-normative reason for the current state, if any.\n",
"type": "string"
},
"Expiry": {
"description": "If the order was created with Capture false, and the payment is authorized, the RFC 3339 time at which this order expires. If further authentication is required, this is the time by which that authentication must be completed.\n",
"type": "string",
"format": "date-time"
},
"Action": {
"description": "If additional action must be taken to proceed with a request, this object contains information about the required action. As of version 20 of this specification, multiple actions may be present, and the supplier may choose which action to invoke.\n",
"type": "object",
"properties": {
"Redirect": {
"description": "The consumer must be redirected to the URL specified to complete the request. Upon completion, the consumer will be redirected to the specified Return URL.\n",
"type": "string",
"format": "uri"
},
"Challenge": {
"description": "The URL to use for iframe-embedded authentication (ex. 3-DSecure v2, WeChat QR code, etc.). For more information, see the [Reach Checkout Web SDK](https://github.com/withreach/reach-sdk-checkout-web).\n",
"type": "string",
"format": "uri"
},
"Display": {
"description": "A freeform JSON object which, in the context of the specified request, gives the necessary information for a consumer to proceed. See https://docs.withreach.com/docs/display-parameters.\n",
"type": "object"
}
}
},
"Times": {
"type": "object",
"properties": {
"Created": {
"description": "The RFC 3339 timestamp at which the order was created.\n",
"type": "string",
"format": "date-time"
},
"Authorized": {
"description": "The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto).\n",
"type": "string",
"format": "date-time"
},
"Processed": {
"description": "The RFC 3339 timestamp at which the order's payment was processed. This will be null if the order's payment has not been processed yet or has failed to be processed.\n",
"type": "string",
"format": "date-time"
}
},
"required": [
"Created"
]
},
"ConsumerCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"Consumer": {
"description": "A Consumer is the person paying for an order and is sometimes referred to as the billing contact. This information must match the address on file for the payment method used.\n",
"type": "object",
"properties": {
"Name": {
"description": "The consumer's full name.\n",
"type": "string"
},
"Company": {
"description": "The company associated with the consumer, when applicable. Required if a corporate NationalIdentifier is specified (e.g. CNPJ in Brazil).\n",
"type": "string"
},
"Email": {
"type": "string"
},
"Phone": {
"description": "The consumer's phone number is required for some payment methods and/or countries. Ideally specified using E.164 formatting, but this is not enforced.\n",
"type": "string"
},
"Address": {
"description": "The consumer's street address.\n",
"type": "string"
},
"City": {
"description": "The city associated with the consumer's address.\n",
"type": "string"
},
"Region": {
"description": "The ISO-3166-2 subdivision code for the region (state,province, etc.) associated with the consumer's address, not including the country code or dash. (eg NS, not CA-NS). This field may be omitted if there are no states/regions in the specified country.\n",
"type": "string"
},
"PostalCode": {
"description": "The postal code associated with the consumer's address. This field may be omitted if there are no postal codes in the specified country.\n",
"type": "string"
},
"Country": {
"description": "The upper-case ISO 3166 alpha-2 country code associated with the consumer's address.\n",
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"NationalIdentifier": {
"description": "The country-specific unique identifier of the consumer, without punctuation. It is required for some payment methods and/or countries and is commonly related to taxes. Examples are SSN for the United States, SIN for Canada, CPF or CNPJ for Brazil or PAN for India.\n",
"type": "string"
},
"BirthDate": {
"description": "Required for some payment methods and/or countries. Must be specified as YYYY-MM-DD.\n",
"type": "string",
"format": "date"
},
"IpAddress": {
"description": "If the request does not originate from the consumer's browser and a consumer-initiated PaymentModel is specified, the IP address of the consumer must be specified before authorization.\n",
"oneOf": [
{
"type": "string",
"format": "ipv4"
},
{
"type": "string",
"format": "ipv6"
}
]
},
"ConsumerProfile": {}
},
"required": [
"Name",
"Email",
"Address",
"City",
"Country"
]
},
"Consignee": {
"description": "A consignee is the person receiving an order. This is sometimes referred to as the shipping contact. Consignee must be specified if Shipping is present.\n",
"type": "object",
"properties": {
"Name": {
"description": "The consignee's full name.\n",
"type": "string"
},
"Company": {
"type": "string"
},
"Email": {
"type": "string"
},
"Phone": {
"description": "The consignee's phone number. Ideally specified using E.164 formatting, but this is not enforced.\n",
"type": "string"
},
"Address": {
"description": "The consignee's street address.\n",
"type": "string"
},
"City": {
"description": "The city associated with the consignee's address.\n",
"type": "string"
},
"Region": {
"description": "The ISO-3166-2 subdivision code for the region (state,province, etc.) associated with the consumer's address, not including the country code or dash. (eg NS, not CA-NS). This field may be omitted if there are no states/regions in the specified country.\n",
"type": "string"
},
"PostalCode": {
"description": "The postal code associated with the consignee's address. This field may be omitted if there are no postal codes in the specified country.\n",
"type": "string"
},
"Country": {
"description": "The upper-case ISO 3166 alpha-2 country code associated with the consignee's address.\n",
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"AddedDate": {
"description": "The date when this address was first used with the supplier. May be a YYYY-MM-DD date or ThisTime.\n",
"type": "string",
"pattern": "^\\d{4}\\-(0[1-9]|1[012])\\-(0[1-9]|[12][0-9]|3[01])|ThisTime$"
},
"VerifiedAddress": {
"description": "Has this address been verified, e.g. by previously using it as a billing address for a card payment.\n",
"type": "boolean"
}
},
"required": [
"Name",
"Address",
"City",
"Country"
]
},
"Payment": {
"description": "Most recently finished payment information regardless of success. This will not be present in an order for which payment has not been attempted.\n",
"type": "object",
"properties": {
"Method": {
"description": "The Reach canonical name of the payment method used.\n",
"type": "string"
},
"Class": {
"description": "The class of the payment method will be one of the following:
**Card** - (ex: VISA, MC)
**Offline** - (ex: BOLETO, BANK)
**Online** - (ex: PAYPAL, EFT)\n",
"type": "string",
"enum": [
"Card",
"Offline",
"Online"
]
},
"AccountIdentifier": {
"description": "When a Card is used, this will be a truncated version of the payment card number. For non-Card methods, it will be the email address or other identifying string, if available.\n",
"type": "string"
},
"Expiry": {
"description": "The last month that the payment information is valid, in format YYYY-MM.\n",
"type": "string",
"pattern": "^\\d{4}\\-(0[1-9]|1[012])$"
},
"NetworkPaymentReference": {
"description": "The payment reference returned by the payment network, if applicable. For subsequent payments using externally stored payment details, this may be specified as PreviousNetworkPaymentReference.\n",
"type": "string"
}
},
"required": [
"Method",
"Class"
]
},
"Items": {
"type": "array",
"items": {
"type": "object",
"required": [
"Sku",
"Quantity",
"MerchantPrice",
"ConsumerPrice"
],
"properties": {
"Sku": {
"type": "string"
},
"Quantity": {
"type": "number",
"format": "double"
},
"MerchantPrice": {
"description": "The price of the item in the supplier's currency.\n",
"type": "number",
"format": "double"
},
"ConsumerPrice": {
"type": "number",
"format": "double"
}
}
}
},
"Shipping": {
"type": "object",
"properties": {
"Service": {
"type": "string",
"deprecated": true
},
"Reference": {
"type": "string",
"deprecated": true
},
"MerchantBreakdown": {
"description": "The shipping breakdown values in the supplier's currency.\n",
"type": "object",
"properties": {
"Duty": {
"type": "number",
"format": "double"
},
"Price": {
"type": "number",
"format": "double"
},
"Taxes": {
"type": "number",
"format": "double"
}
},
"required": [
"Duty",
"Price",
"Taxes"
]
},
"ConsumerBreakdown": {
"type": "object",
"properties": {
"Duty": {
"type": "number",
"format": "double"
},
"Price": {
"type": "number",
"format": "double"
},
"Taxes": {
"type": "number",
"format": "double"
}
},
"required": [
"Duty",
"Price",
"Taxes"
]
}
},
"required": [
"MerchantBreakdown",
"ConsumerBreakdown"
]
},
"Charges": {
"type": "array",
"items": {
"type": "object",
"required": [
"Name",
"MerchantPrice",
"ConsumerPrice"
],
"properties": {
"Name": {
"type": "string"
},
"MerchantPrice": {
"description": "The price of the charge in the supplier's currency.\n",
"type": "number",
"format": "double"
},
"ConsumerPrice": {
"type": "number",
"format": "double"
}
}
}
},
"Discounts": {
"type": "array",
"items": {
"type": "object",
"required": [
"Name",
"MerchantPrice",
"ConsumerPrice"
],
"properties": {
"Name": {
"type": "string"
},
"MerchantPrice": {
"description": "The value of the discount in the supplier's currency.\n",
"type": "number",
"format": "double"
},
"ConsumerPrice": {
"type": "number",
"format": "double"
}
}
}
},
"Financing": {
"type": "object",
"properties": {
"Instalments": {
"type": "integer"
},
"MerchantPrice": {
"description": "The price of the financing option in the supplier's currency.\n",
"type": "number",
"format": "double"
},
"ConsumerPrice": {
"type": "number",
"format": "double"
}
},
"required": [
"Instalments",
"MerchantPrice",
"ConsumerPrice"
]
},
"MerchantTotal": {
"description": "The total amount charged to the consumer in the supplier's currency. Note that this includes all fees, which will not be remitted to the supplier.\n",
"type": "number",
"format": "double"
},
"ConsumerTotal": {
"description": "The total amount charged to the consumer in the consumer's currency.\n",
"type": "number",
"format": "double"
},
"Store": {
"type": "string"
},
"Refunds": {
"description": "If any refunds have been submitted for this order, details will appear in this array.\n",
"type": "array",
"items": {
"type": "object",
"required": [
"RefundId",
"ConsumerAmount",
"State",
"ReferenceId",
"StartTime",
"ProcessedTime"
],
"properties": {
"RefundId": {
"description": "The external uuid of the refund assigned by Reach.\n",
"type": "string",
"format": "uuid"
},
"ConsumerAmount": {
"description": "The amount of the refund in the consumer currency. This amount may not be the total order amount if a partial refund has been submitted. However, the sum of all refund amounts will not exceed the total order amount.\n",
"type": "number",
"format": "double"
},
"MerchantAmount": {
"description": "The amount of the refund in the supplier currency. This will be null if the amount is not yet known.\n",
"type": "number",
"format": "double"
},
"State": {
"description": "See documentation on [Refund States](https://docs.withreach.com/docs/states-and-events#section-refunds).\n",
"type": "string"
},
"ReferenceId": {
"description": "The reference id for this refund.\n",
"type": "string"
},
"StartTime": {
"description": "The RFC 3339 timestamp at which the refund was created.\n",
"type": "string",
"format": "date-time"
},
"ProcessedTime": {
"description": "The RFC 3339 timestamp at which the refund was processed.\n",
"type": "string",
"format": "date-time"
}
}
}
},
"ThreeDS": {
"description": "Details regarding the 3D Secure authentication results.\n",
"type": "object",
"properties": {
"Eci": {
"description": "The Electronic Commerce Indicator (ECI) value returned by the payment processor. This indicates the authentication level and whether a liability shift occurred. For more informaiton view [ECI values](https://docs.withreach.com/docs/eci-values).\n",
"type": "string",
"maxLength": 2,
"example": "05"
},
"MessageVersion": {
"description": "The version of the 3D Secure protocol used for the transaction (e.g., '2.3.1').\n",
"type": "string",
"example": "2.2.0"
}
}
},
"Meta": {
"type": "object"
}
}
},
{
"title": "(ReferenceId) Orders associated with the ReferenceId.\n",
"type": "object",
"properties": {
"MerchantId": {
"description": "The 36 character GUID which identifies the supplier to the Reach system.\n",
"type": "string",
"format": "uuid"
},
"Orders": {
"description": "An array (which may be empty) of Reach order data for orders whose reference matches the specified Reference.\n",
"type": "array",
"items": {
"type": "object",
"properties": {
"OrderId": {
"description": "The 36 character GUID which identifies the order in the Reach system.\n",
"type": "string",
"format": "uuid"
},
"OrderState": {
"description": "See documentation on [Order States](https://docs.withreach.com/docs/states-and-events#section-orders).\n",
"type": "string"
},
"Times": {
"type": "object",
"properties": {
"Created": {
"description": "The RFC 3339 timestamp at which the order was created.\n",
"type": "string",
"format": "date-time"
}
},
"required": [
"Created"
]
}
}
}
}
}
},
{
"title": "(ContractId) Information about the contract.\n",
"type": "object",
"properties": {
"MerchantId": {
"description": "The 36 character GUID which identifies the supplier to the Reach system.\n",
"type": "string",
"format": "uuid"
},
"ContractId": {
"description": "The unique identifier for the Reach contract.\n",
"type": "string",
"format": "uuid"
},
"ReferenceId": {
"description": "The reference id passed into the system, if the contract was created using openContract.\n",
"type": "string"
},
"ConsumerCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"Consumer": {
"description": "The consumer associated with the contract. It may only be unset for unopened PayPal contracts.\n",
"type": "object"
},
"Payment": {
"description": "The payment information associated with the contract.\n",
"type": "object",
"properties": {
"Method": {
"description": "The Reach canonical name of the payment method used.\n",
"type": "string"
},
"Class": {
"description": "The class of the payment method will be one of the following:
**Card** - (ex: VISA, MC)
**Offline** - (ex: BOLETO, BANK)
**Online** - (ex: PAYPAL, EFT)\n",
"type": "string",
"enum": [
"Card",
"Offline",
"Online"
]
},
"AccountIdentifier": {
"description": "When a Card is used, this will be a truncated version of the payment card number. For non-Card methods, it will be the email address or other identifying string, if available.\n",
"type": "string"
},
"ProviderReference": {
"description": "The payment provider's reference to the contract, if available. For example, the PayPal billing agreement identifier.\n",
"type": "string"
},
"Expiry": {
"description": "The last month that the payment information is valid, in format YYYY-MM.\n",
"type": "string",
"pattern": "^\\d{4}\\-(0[1-9]|1[012])$"
},
"NetworkPaymentReference": {
"description": "The payment reference returned by the payment network for the initial authorization in the contract, if applicable. For subsequent payments using externally stored payment details, this may be specified as PreviousNetworkPaymentReference.\n",
"type": "string"
}
}
},
"Times": {
"type": "object",
"properties": {
"Opened": {
"description": "The RFC 3339 timestamp at which the contract was open.\n",
"type": "string",
"format": "date-time"
},
"Closed": {
"description": "The RFC 3339 timestamp at which the contract was closed.\n",
"type": "string",
"format": "date-time"
},
"Expiry": {
"description": "The RFC 3339 timestamp at which the contract will expire, or has expired.\n",
"type": "string",
"format": "date-time"
}
}
},
"Orders": {
"description": "An array (which may be empty) of Reach order data for orders whose ContractId matches the specified ContractId.\n",
"type": "array",
"items": {
"type": "object",
"properties": {
"OrderId": {
"description": "The 36 character GUID which identifies the order in the Reach system.\n",
"type": "string",
"format": "uuid"
},
"OrderState": {
"description": "See documentation on [Order States](https://docs.withreach.com/docs/states-and-events#section-orders).\n",
"type": "string"
},
"ReferenceId": {
"description": "The reference id passed into the system when the order was created.\n",
"type": "string"
},
"Times": {
"type": "object",
"properties": {
"Created": {
"description": "The RFC 3339 timestamp at which the order was created.\n",
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
]
}
}
}
},
"400": {
"description": "The query request structure was invalid and unable to be parsed.\n"
},
"404": {
"description": "No matches to the provided order, reference, or contract.\n"
},
"503": {
"description": "There was a system problem and the request should be tried again.\n"
}
},
"tags": [
"POST"
]
}
}
},
"tags": [
{
"name": "POST"
}
],
"x-explorer-enabled": false,
"x-readme": {
"proxy-enabled": true
},
"x-samples-enabled": false
}
```