Cancel-Replace or Amend on Binance: What You Keep and Lose

One intention, two operations

A trader reducing a resting bid from 5.5 BTC to 5.0 has one intention and two mechanisms available. They behave differently in the order book, in the rate-limit ledger, and in what the fill report looks like afterwards.

The distinction matters most for maker orders. A resting order earns the maker rate and holds a position in the queue at its price. That position is an asset: it determines who gets filled first when a taker arrives. Cancelling and re-placing spends that asset silently, because the new order looks identical in every field except the two that matter — its id and its place in line.

Binance is unusually explicit about this. Its amend FAQ walks a concrete book: a buy at 87,000 with orders of 1.00, 5.50, 4.00 at the same price, where your 5.50 is second. Reduce to 5.00 by cancel-replace and the new order sits behind the 4.00 that used to be behind you. Reduce by amend and the order stays second, with the same order id.

Cancel-replace: two operations in one request

POST /api/v3/order/cancelReplace cancels an existing order and places a new one on the same symbol. It is not an edit. It is a bundle, and the bundle can half-fail.

The documented behaviour worth knowing before using it:

• Filters and the order count are evaluated before either half runs. A request that will breach a filter fails before the cancel, which is the safe ordering.
• A new order that was never attempted still counts. Binance states that when newOrderResult is NOT_ATTEMPTED, the unfilled order count still increases by 1.
• Only an individual order can be cancelled from an order list, though Binance notes the result is the same as cancelling the entire list.
• Weight is 1 and the unfilled order count is 1 — cheap by weight, expensive by count.
• HTTP 409 signals a partial success, and the body carries cancelResult and newOrderResult separately.

Two parameters decide the failure policy, and they are easy to confuse:

STOP_ON_FAILURE is the conservative choice for a strategy that must not be exposed twice. ALLOW_FAILURE is the choice when the cancel is expected to fail sometimes — a chase loop cancelling an order that just filled — and the new price is more important than the cancel succeeding. Neither is universally right, but the difference between them is the difference between “no position change” and “possibly two positions”, so it should be a deliberate setting rather than a default.

The cancelRestrictions parameter earns its place in the same scenario. Without it, a cancel aimed at a NEW order will also succeed against one that has already partially filled, which can leave the strategy with a residual position it did not plan for. Restricting the cancel to ONLY_NEW turns that race into an explicit failure the code can see.

The two failures are documented as separate codes, and the distinction is the one an automated client needs: -1145 Invalid cancelRestrictions means the request was malformed and will never succeed as written, while -2011 Order was not canceled due to cancel restrictions means the order had already moved past the state the caller allowed. The first is a bug to fix. The second is the race the parameter exists to make visible, and a retry loop that treats it as transient will retry forever against an order that has legitimately left NEW.

Amend keep-priority: one field, no queue loss

PUT /api/v3/order/amend/keepPriority reduces the quantity of an existing open order in place. That is the entire surface.

• The only mandatory change is newQty, which must be greater than zero and less than the order’s current quantity.
• The order id stays the same unless you pass a newClientOrderId, and Binance allows you to reuse the current client order id.
• Weight is 4 and the unfilled order count is 0. The endpoint adds nothing to the exchange’s order-count filters.
• A failure of any kind — filters, permissions, account restrictions — leaves the original order unchanged.
• Orders inside an order list can be amended.
• An iceberg’s visible quantity changes only when the new quantity is below the pre-amend visible quantity.

That last point is a good illustration of what “amend” means mechanically. The order is not rebuilt; one number in an existing book entry changes. Anything that depended on the old number keeps its shape.

The confirmation arrives in two places. The REST response returns the amended order, and the user data stream emits an executionReport with execution type REPLACED. Both are worth checking: a response that arrives but an event that does not is a signal that something is being filtered between the engine and your socket.

Choosing between them

The decision rule is short enough to state plainly, then hard to apply consistently.

Use amend when only the quantity falls. If the order’s price, side and type stay the same and the new size is smaller, amend is cheaper on the order count, cheaper on queue position, and leaves the order’s identity intact for downstream reconciliation. There is no reason to cancel and replace in that case.

Use cancel-replace when anything else changes. A price move, a size increase, a change of time-in-force or order type. Queue priority is lost either way, so the only remaining question is whether the strategy can tolerate a partial outcome — which is what cancelReplaceMode decides.

Do neither when the order is already gone. A chase loop that cancels on every tick spends order count and queue position whenever the order has already filled. Reading the order state first, or accepting the -2011 unknown-order response as a normal outcome, costs one request instead of two.

The rate-limit arithmetic is what makes the choice more than stylistic. Unfilled-order counts are typically tight — Binance publishes an ORDERS limit per 10 seconds and a daily cap in its exchange information — while request weight is comparatively generous. An amendment-heavy strategy burns weight and preserves count. A replace-heavy one does the opposite. For a market maker quoting around a level, that difference is the difference between hitting the order limit at midday and not.

What amendment cannot do

It cannot express intent about price. It cannot increase size, because the documented requirement is a quantity strictly less than the current one. It cannot convert a resting order into an iceberg, or change time-in-force. Each of those is a new order, with a new place in line, priced as one.

The related mechanisms are worth reading together. Time in force decides whether an order ever rests, which decides whether queue priority is worth anything. OCO, OTO and trailing stops put orders inside lists, where amending one member has consequences for the group’s conditional logic. And the maker side of the fee schedule — the reason a resting fill is worth protecting — is set out in maker and taker orders.

One operational note closes the loop. An amend that fails leaves the order untouched, which is a good property and a trap: a bot that logs “amend sent” and stops tracking will not notice that its size never changed. The confirmation is the REPLACED execution report, not the request.

Risk note. Endpoint behaviour, weight, limits and queue semantics in this article were read from Binance’s Spot API documentation and amendment FAQ on 2026-10-30. Exchange rules change; the distinction between replacing an order and editing one does not. Nothing here is investment advice.