Create Instant Order 🆕

Facilitates the creation of a new order containing exactly one product with a quantity of one per request. Upon receiving the client request, the API will immediately initiate the order fulfillment process.

The API will briefly attempt to fulfill the order by checking existing inventory. If the requested product is available in stock, it reserves the product for immediate fulfillment and returns a response with status COMPLETED. Clients can then retrieve their code using the GetCodes API.

If the inventory lookup finds that the requested stock is unavailable, the API initiates an asynchronous fulfillment process. In this case, the API immediately returns a response with status PROCESSING. Clients are responsible for periodically polling the order status via the provided transaction ID until the order status transitions to COMPLETED, indicating availability for retrieval.

Note: The API does not maintain an active connection for up to 30 seconds anymore. It returns immediately after attempting the initial inventory lookup, responding with either a COMPLETED or PROCESSING status.

POST /v2/orders/instant

Request

HTTP Headers

To use this endpoint, you must include the following headers for authentication and authorization:

Header	Type	Required	Description
x-api-key	String	Yes	API key assigned to your account for service access.
Authorization	String	Yes	Bearer token to authenticate the API request.

Payload

Property	Type	Required	Default Value	Description
clientOrderNumber	String	No	None	The order number assigned by the client, used for tracking and reference purposes.
enableClientOrderNumberDupCheck	Boolean	No	false	Enable to prevent duplicate clientOrderNumber
sku	String	Yes		The Stock Keeping Unit identifier for the product.
payWithCurrency 🆕	String	No*	None	Settlement currency (ISO-4217). See rules below. Required only when the product currency is not in the customer’s balance currencies.

*payWithCurrency is required only when the product currency is not present in the customer’s balance currencies. If omitted otherwise, the system defaults to the product currency; if the customer has a single balance currency equal to the product currency, the default is applied automatically. If payWithCurrency is provided but not in the customer’s balances, the API returns UNSUPPORTED_CURRENCY.

Cross-currency settlement (payWithCurrency)

Settle an order in a currency different from the product’s currency.

Property: payWithCurrency (ISO‑4217, e.g., USD)

Rules

• If the product currency is in your balances and payWithCurrency is omitted, the order settles in the product currency (default).
• If the product currency is not in your balances, payWithCurrency is required; omitting it returns UNSUPPORTED_CURRENCY.
• If payWithCurrency is provided but not in your balances, the API returns UNSUPPORTED_CURRENCY.
• If you have a single balance currency equal to the product currency, the system defaults to that currency; you may still override it.

Example Request

POST /v2/orders/instant HTTP/1.1
Host: api.example.com
Content-Type: application/json
x-api-key: <API_KEY>
Authorization: Bearer <BEARER_ACCESS_TOKEN>

{
  "clientOrderNumber": "1234",
  "sku": "8PX-UF-Y5U"
}

Example Request (Cross-Currency)

POST /v2/orders/instant HTTP/1.1
Host: api.example.com
Content-Type: application/json
x-api-key: <API_KEY>
Authorization: Bearer <BEARER_ACCESS_TOKEN>

{
  "clientOrderNumber": "po-1234",
  "sku": "TTR-WI-YWN",
  "payWithCurrency": "USD"
}

Responses

HTTP Status Codes

Status Code	Description
200	OK
400	Bad Request
409	Conflict (e.g., duplicate clientOrderNumber when duplication check is enabled)
422	Unprocessable Entity (e.g., invalid or missing payWithCurrency when required)
500	Internal Server Error

Schema

Property	Type	Nullable	Description
requestId	String	No	Unique identifier assigned to each request for tracking purposes.
data	OrderResponse	No	Order response.

OrderResponse

Property	Type	Nullable	Description
transactionId	String	No	The transaction identifier.
clientOrderNumber	String	No	The client's order number.
payWithCurrency	String	No	The currency used to settle/charge the order.
grandTotal	MoneyResponse	No	The grand total amount and currency.
createdAt	String	No	Timestamp of when the order was created.
status	OrderStatus	No	The status of the order.
products	ProductResponse[]	No	List of products in the order.
fxSummary	FxEntry[]	Yes	Summary of FX pairs/rates used when cross-currency conversion is applied. Omitted for same-currency orders.

ProductResponse

Property	Type	Nullable	Description
sku	String	No	The SKU of the product.
quantity	Integer	No	Always 1 for Instant orders.
unitPriceOriginal	MoneyResponse	Yes	Unit price in the product’s native currency before FX. Optional; omitted when same-currency.
unitPrice	MoneyResponse	No	The unit price of the product.
totalPrice	MoneyResponse	No	The total price of the product.
status	OrderStatus	No	The status of the product.

MoneyResponse

Property	Type	Nullable	Description
amount	String	No	The monetary amount.
currency	String	No	The currency of amount.

FxEntry

Property	Type	Nullable	Description
pair	String	No	Currency pair used (e.g., EUR/USD).
rate	Number	No	Applied FX rate for the pair.
asOfDate	String	No	ISO date/time when the rate was effective.

OrderStatus

Value	Type	Description
PROCESSING	String	The order is currently being processed.
COMPLETED	String	The order has been completed successfully.
CANCELLED	String	The order has been cancelled and will not be processed.

Example 200 OK Response

{
  "requestId": "c4c7b997-79a5-4bde-9f17-47ad7eac9ed4",
  "data": {
    "transactionId": "1234",
    "clientOrderNumber": "po-1234",
    "payWithCurrency": "USD",
    "grandTotal": {
      "amount": "9.75",
      "currency": "USD"
    },
    "createdAt": "2025-10-06T09:00:00Z",
    "status": "COMPLETED",
    "products": [
      {
        "sku": "TTR-WI-YWN",
        "quantity": 1,
        "unitPriceOriginal": { "amount": "9.70", "currency": "EUR" },
        "unitPrice": { "amount": "11.48", "currency": "USD" },
        "totalPrice": { "amount": "11.48", "currency": "USD" },
        "status": "COMPLETED"
      }
    ],
    "fxSummary": [
      { "pair": "EUR/USD", "rate": 1.1829, "asOfDate": "2025-10-06" }
    ]
  }
}

Example Error Responses

UNSUPPORTED_CURRENCY (product currency not in balances and payWithCurrency missing or not supported)

{ "error": "UNSUPPORTED_CURRENCY", "message": "payWithCurrency is required or not supported for this account." }

CLIENT_ORDER_NUMBER_DUPLICATE (dup-check enabled)

{ "error": "CLIENT_ORDER_NUMBER_DUPLICATE", "clientOrderNumber": "1234" }