Orders

1. 1Quote→
2. 2Confirm→
3. 3Order→
4. 4Route→
5. 5Fill→
6. 6Position

Confirmation is an input to this pipeline, never a shortcut around it. The order row is written before anything is sent, because an execution that succeeds upstream and then fails to be recorded is the one outcome with no recovery path.

POST /quotes
   │
   ▼  POST /orders  { executionIntent: "record_intent" }
reserve_pending             recorded, NOT YET EXECUTABLE
   │
   │  you reserve authorizationAmount in YOUR ledger
   ▼  POST /orders/{id}/confirm-reserve
pending_venue_execution     reserve confirmed, cleared to execute
   │
   ▼
submitted ─▶ filled | partially_filled | rejected
   │
   └─▶ unknown after timeout ─▶ 409 reconciliation_required

The two reserve states are the reason the diagram does not start at submitted: an order is recorded and funded before it can execute. A sandbox tenant, or any caller sending executionIntent: "simulate", skips them and lands directly on a simulated fill.

settlementState collapses every status to the only question a wallet has to answer right now: is the money final, or must I hold and come back? Switch on it, and submitted can never be mistaken for terminal. An order awaiting execution is pending for the same reason an unresolved one is: it may still execute. To tell those two apart, read transmissionState.

{
  "quoteId": "fc3be731-98dc-4c03-80ac-23576a708d9c",
  "clientOrderId": "ticket-9031"    // YOUR id. The idempotency key.
}

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "clientOrderId": "ticket-9031",
  "status": "filled",
  "contractId": "ctr_9f31c2…",
  "side": "YES",
  "action": "buy",
  "filledQuantity": 68.6111,
  "averagePrice": 0.72,
  "platformFee": 0.6,
  "platformFeeBps": 120,
  "predictaFee": 0.6,
  "predictaFeeBps": 120,
  "notional": 49.4,
  "stake": 50,
  "rejectReason": null,
  "simulated": true,
  "createdAt": "2026-08-20T04:43:40.282Z",
  "idempotentReplay": false,
  "routing": { "reason": "only_venue", "consideredVenues": 1 },

  "operatorMoney": {
    "currency": "USD",
    "authorizationAmount": "50.00",   // what you reserved
    "actualDebit": "50.00",           // TAKE THIS
    "releaseAmount": "0.00",          // GIVE THIS BACK
    "tradeAmount": "49.40",
    "platformFee": "0.60",
    "venueFee": "0.00",
    "venueFeeKnown": false
  },
  "operatorExitMoney": null
}

A sell is a credit, and carries a different object

On an exit operatorMoney is null, deliberately, and operatorExitMoney.sellProceeds is what to credit, already net of the platformFee and venueFee reported beside it. A single object for both directions would hand a wallet an authorizationAmount on a trade that pays cash out, and a partner applying the contract as written would debit the player for selling their own position.

clientOrderId is unique per operator and player, enforced by a database index rather than by a check in application code. Two requests arriving together produce one order; the loser of the race re-reads the winner's.

• Derive the key from the reservation in your own ledger. A random value per attempt gives you no protection at all, because a retry has to present the same string. A clock gives you a key you cannot reproduce after a crash.
• A rejected order still consumes its key. Retrying a spent key after a rejection must not open a second live order, so the rejected record stays.

# 1. You have an orderId. Poll it. This route carries settlementState.
GET /api/v1/orders/{orderId}
→ { "status": "submitted", "settlementState": "pending", "transmissionState": "unknown",
    "operatorMoney": { "actualDebit": "0.00", "releaseAmount": "50.00", … } }

# 2. You never received a response at all. Look the order up by YOUR id.
GET /api/v1/orders?externalUserId=user-4471&clientOrderId=ticket-9031
→ { "orders": [ { "orderId": "3dd27f36-…", "status": "submitted", … } ],
    "count": 1, "nextCursor": null, "hasMore": false }

# 3. Then read THAT orderId back with step 1. The list route does not
#    carry settlementState, so it finds the order; it does not settle it.

• clientOrderId is the identifier that survives a crash mid-request: you chose it before the request was sent. Parity's orderId only ever existed in a response you may not have received.
• It is unique within a user, so it must be sent with externalUserId. Alone it is 400 invalid_request: a question with no single answer, and returning the first match would silently pick one.
• The lookup is a filter on the list route rather than a second endpoint, so a reconciler uses one call for “this one order” and “everything since 09:00”.
• The list route does not return settlementState or transmissionState. Only GET /api/v1/orders/{id} computes them. So the recovery is two calls: find the order by your clientOrderId, then read that orderId back. Branching on settlementState from a list response reads undefined, and a wallet that treats undefined as “not pending” releases a hold it must keep.
• While unresolved, the read reports actualDebit of "0.00" with the whole authorization as releaseAmount. That is a description of an unfinished order, not an instruction to release: settlementState is what tells you whether to act.

import { ReconciliationRequiredError } from '@/sdk';

try {
  const order = await player.submitOrder({ quoteId, clientOrderId: 'ticket-9031' });
  ledger.settle(order.operatorMoney);
} catch (err) {
  if (err instanceof ReconciliationRequiredError) {
    // err.holdAuthorization === true. Keep the hold.
    const found = await player.findOrderByClientOrderId('ticket-9031');
    if (!found) return schedulePoll();          // not visible yet: hold and retry

    // findOrderByClientOrderId reads the LIST route, which carries no
    // settlementState. Read the order itself for the verdict.
    const order = await player.getOrder(found.orderId);
    if (order.settlementState === 'pending') return schedulePoll();
    return apply(order.operatorMoney);
  }
  throw err;
}

Paging is keyset for the same reason as the catalogue: orders arrive while you page, and an offset would let one placed between two requests push an older order across the page boundary where you never see it. A missing trade, reported as a successful page.

• Every order leaves the API through the same serialiser the POST response uses. A stored POST response and a later GET describe the order identically, and the fields most likely to differ between two shapes are exactly the ones that decide money.
• An order belonging to another partner returns the same 404 unknown_order as one that does not exist. Distinguishing them would make the route an oracle for whether a guessed id is real.

Why fills are nested under an order

There is no top-level fills feed, and that is deliberate. A fill carries no money contract of its own: operatorMoney belongs to the order, computed once over the whole execution. A partner booking per fill double-counts the moment a venue fills one order in two pieces. Fills are a reconciliation detail (fillId, quantity, price, filledAt) and are off by default because the order already carries the average price, the filled quantity and the money.

An order is recorded before it is executable, and it becomes executable when you confirm that the customer's funds are held. That handshake is what executionIntent: "record_intent" on POST /api/v1/orders asks for, and it is the default for a live tenant. A sandbox tenant defaults to the simulated fill instead, because a sandbox exists so that a fill can be made to happen.

The order comes back with a real Parity orderId and an actualDebit of 0.00, the whole authorization showing as releaseAmount: at the moment an order is recorded, nothing has been spent.

The sequence, and why it has two stops

• POST /api/v1/orders records the order and reserves against it. Status reserve_pending. It cannot execute. Parity will never transmit an order whose reserve you have not confirmed.
• You place the hold on your customer's funds, for the exact authorizationAmount we returned.
• POST /api/v1/orders/{id}/confirm-reserve, optionally with your own reserveReference. Status pending_venue_execution: the order is now cleared to execute. If you reserve BEFORE calling us, send reserveReference on the order itself and skip a round trip.

When confirm-reserve refuses

Every step recovers from your own id

No call here asks you to remember anything we do not already hold. If the order POST times out, resend it: the same clientOrderId replays the original rather than opening a second. If the confirmation times out, resend it, or read the order back with GET /api/v1/orders?externalUserId=&clientOrderId=: it says reserve_pending or pending_venue_execution and there is no third answer.

How long an order sits in pending_venue_execution

Confirming the reserve clears an order to execute. It does not transmit it. Transmission additionally requires that venue execution is enabled for your deployment and that this specific order has been armed, which is a deliberate per-order act rather than something an order acquires by being placed. Until both are true the order stays pending_venue_execution with transmissionState: not_transmitted.

That is a safe place for an order to be, and it is readable: nothing was sent, so the order is still cancellable and its release instruction is exact. What it is not is a transient state you should assume will clear on its own. Whether venue execution is enabled for your deployment is settled with Parity as part of going live, not through this API. Build the handshake and the hold now; ask us what is armed before you point real customers at it.

transmissionState, and the question it answers

settlementState answers “may I apply the money yet?”. transmissionState answers the other question, and they are not the same:

Cancelling, exactly once

• A second call returns 200 with the same cancellationId and the same releaseAmount, and idempotentReplay: true. A cancellation whose response you never saw is safe to resend and cannot credit a customer twice.
• It refuses any order whose transmissionState is not not_transmitted, and reconciliation_required above all. That is the state where we asked a venue and got no answer, and a release issued against one would hand your customer back money standing behind a position that may really exist. The 409 carries transmissionState: "unknown", which says the right thing: keep holding, and wait for reconciliation.

The quoted price is a ceiling. If the book has moved past it by the time the order is submitted, the order is rejected rather than filled: the player agreed to a number, and a fill at a worse one is not the trade they confirmed.

A filled order opens or extends a position, readable at GET /api/v1/positions and GET /api/v1/positions/{id}. A position carries operatorMoney.costBasis and operatorMoney.realisedPnl, which are facts, not instructions: cash already debited, and P&L already booked. There is no mark-to-market: a number that moves on its own is not something a ledger can reconcile against, and a partner who wants the mark quotes a sell.

Every money fact an order produces also lands on the reconciliation feed (order.state_changed, order.filled, fee.assessed, collateral.moved), totally ordered and resumable. See Reconciliation.