Where a broker order id comes from
brokerOrderId is the venue’s own id for one order. Three places hand it to you, and they agree:
It is the venue’s id, not ours, and a composite re-place can mint a new one — so read it back from
the response rather than assuming it survived.
1
Move a resting order to a new price
Replace an order is one operation under one
idempotency key.
orderType must match the type the engine reports for that order, or the call
is refused with 400 order_type_mismatch.price is a limit’s resting price, a stop’s trigger, and a stop_limit’s trigger. A
stop_limit also needs stopLimitPrice — the limit its trigger converts to.2
Read the outcome, not the status code
The engine amends natively where the venue truly amends, keeping the order’s identity, and runs
a typed composite everywhere else. A
200 therefore does not mean the move worked. outcome
is the truth to surface:The contract names
amended and replaced as the successes; treat everything else as a state
to show the trader, not a failure to retry blindly.3
Carry the exits through the replace
Send The same call can also change the exits:
restoreBracket — the order’s current exits as you know them — on every replace of an
entry that has exits attached. Without it, a rejected re-place restores the entry without its
exits, and that is what restored_without_bracket reports.stopLoss and takeProfit here are end states — an
object sets the leg, null removes it, omitting it leaves it alone.4
Cancel one order
Cancel an order takes the broker order id and nothing
else.The engine answers only after the venue accepts the cancel, and the copier mirrors it to
follower accounts only after that acceptance, so leaders and followers never disagree about
what rests. Either way, the account stream is the truth of what remains.
5
Sweep the book
Cancel all working orders cancels every
working order. Pass A successful sweep reports the cancelled count. If a venue rejection interrupts it, the answer
is not a success: it carries
instrument to scope the sweep to one; omit it to cancel across all
instruments.cancel_all_incomplete plus the number actually cancelled, so you
re-sync and re-issue rather than believing the book is clear.Idempotency across retries
Replacing is a money-path mutation, so it carriesclientOrderId — one intent, one id, and a
retry of the same intent can never run the move twice. Mint a new id when the trader drags the
order somewhere new; reuse the id when you are retrying the same drag after a timeout.
Cancelling is different. Cancels are idempotent at the venue, so neither cancel route takes an
idempotency key, and a re-issue after a partial failure is safe.
A risk-locked account answers 423 to the replace route. Neither cancel route lists a 423: the
lock gates new exposure, and a cancel only removes it.
Where to go deeper
- Idempotency — what a claim is and why a retry is safe.
- Errors — the shape of every refusal, and which ones mean stop.
- Close a position — the four ways out, and what each cancels first.
- Protect a position — the stop and target the replace has to carry.