Get an order by your reference
Returns the same order detail as GET /v1/orders/{id}, found by the
merchant_order_id you sent when placing it. Use it when you never
got the create response — a timeout, a dropped connection: placing the
order again with the same merchant_order_id is refused as a
duplicate, and this tells you what became of the first one.
The match is exact and case-sensitive. An order that was never created
is 404, exactly like an unknown id.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
The merchant_order_id you sent to POST /v1/orders.
Response
Units delivered so far (relevant for key items / partials).
Amount refunded for undelivered units (partial / failed).
The submitted input fields (choice values shown as their display name).
The order’s current state. Three are non-terminal (it will still move) and three are terminal (it never changes again):
pending— accepted and charged; fulfillment has not started. Non-terminal.processing— fulfillment is running at the provider. Non-terminal.need_client_code— PAUSED awaiting a confirmation code the provider sent to your end customer. Polling stops until you submit it withPOST /v1/orders/{id}/client-code, after which the order returns toprocessing. Only login-method top-ups reach this state, and it is the only status that needs anything from you. Non-terminal.completed— every unit delivered (codes,delivered_quantity). Terminal.partial— some units delivered, the rest refunded (refund_amount,delivered_quantity;erroris usually empty here). Terminal.failed— nothing delivered, charge fully refunded (error,error_message). Terminal.
An order never returns to pending and never moves between terminal statuses;
need_client_code -> processing is the only backwards transition, and only because
you submitted a code.
Stable machine error code (e.g. OUT_OF_STOCK, NOT_ENOUGH_STOCK, INVALID_FIELDS, INSUFFICIENT_BALANCE, ORDER_TIMEOUT); empty otherwise. Always populated when status is failed. On partial it is usually EMPTY — an ordinary short delivery carries no error code, and only a partial that ran out of time reports one (ORDER_TIMEOUT), so do not rely on it to explain every shortfall; compare delivered_quantity against quantity instead. See the Errors guide for the full list of order error codes.
Human-readable text for error; empty whenever error is empty.
Delivered key/code strings (key items only).
Who placed the order. For an order placed through the API, the API key that placed it — id is the key’s id and email is empty — since a key belongs to the account, not to a person. For an order placed in the dashboard, the person and their address.
When the order was fully delivered. Set ONLY when status is completed; stays null on partial and failed even though those are terminal. Test status — not this field — to decide whether an order has settled.
Delivery status of the outbound order-result webhook. Present only for API-placed orders (source: "api") that have a webhook URL configured; null for dashboard orders or when no webhook is set. Lets you see whether the terminal event reached your endpoint. See the Webhooks guide.