Reading orders back
Looking up one order by your own reference, or listing the orders outstanding for a session.
Two reads that answer the question a dropped connection leaves behind: what
happened to my order? Both are recovery routes for
session-bound orders, and both work whether or
not the order was placed with autoSubscribe.
POST /api/3/zm/rest/orders/state?clientRequestId=<your reference>
POST /api/3/zm/rest/orders # all your tracked orders
POST /api/3/zm/rest/orders?sessionId=<session> # narrowed to one session
Both return a JSON array, and an empty array is a valid answer — a
clientRequestId is only unique within your own orders, and you may have reused
one. Both are scoped to the credential making the call; there is no way to read
another party's orders, and the gateway's own transactionId is not accepted as
a filter.
Records are held for 24 hours, and reading one does not extend that. Beyond it, an order that executed is in your trades.
Request
A read is a POST because the body is signed. Every /api/3 call carries its
anti-replay element — tonce or nonce — inside the signed body, so these
reads take a body even though they change nothing. See
making requests for the signature.
The parameters are on the query string, not in the body:
| Field | Type | Required | Notes |
|---|---|---|---|
clientRequestId | string | Conditional | Required on /orders/state. The reference you sent on the order. Maximum 64 characters; an invalid one is rejected with 400 |
sessionId | string | Optional on /orders. Narrows the result to one session. Omit it for every order the credential has outstanding. Maximum 64 characters, no /, whitespace or control characters |
Order state
One element of the returned array.
Unlike the WebSocket order response, subscriptionStatus and sessionId are
always present here, as null when they do not apply, rather than being
omitted from the object.
| Field | Type | Notes |
|---|---|---|
messageType | string | Always orderState |
transactionId | string | Our identifier for the order |
clientRequestId | string | Your own reference, echoed back |
orderStatus | OrderStatus | What happened to the order. An order with no outcome recorded yet reads as PENDING |
subscriptionStatus | SubscriptionStatus | Whether the outcome is still being redelivered over the WebSocket. NOT_SUBSCRIBED for an order placed without autoSubscribe. May be null |
sessionId | string | The session the order is bound to. null for an order placed without autoSubscribe |
message | string | Human-readable detail accompanying code |
code | string | Set when the order failed; see trade error codes |
chanId | string | The connection the order was placed on. Not meaningful on a REST read |
timestamp | integer | When this response was produced, in milliseconds. Not the time of any order event |
OrderStatus
| Value | Meaning |
|---|---|
SUCCESS | The order was executed |
FAILED | The order was not executed. code carries the reason |
INDETERMINATE | |
PENDING | No outcome has been recorded yet. The order may still be in flight |