Modify Order (TRADE)

API Description

Order modify function, currently only LIMIT order modification is supported, modified orders will be reordered in the match queue

HTTP Request

PUT /fapi/v1/order

Request Weight

1 on 10s order rate limit(X-MBX-ORDER-COUNT-10S); 1 on 1min order rate limit(X-MBX-ORDER-COUNT-1M); 0 on IP rate limit(x-mbx-used-weight-1m)

Request Parameters

Name	Type	Mandatory	Description
orderId	LONG	NO
origClientOrderId	STRING	NO
symbol	STRING	YES
side	ENUM	YES	SELL, BUY
quantity	DECIMAL	YES	Order quantity, cannot be sent with closePosition=true
price	DECIMAL	YES
priceMatch	ENUM	NO	only avaliable for LIMIT/STOP/TAKE_PROFIT order; can be set to OPPONENT/ OPPONENT_5/ OPPONENT_10/ OPPONENT_20: /QUEUE/ QUEUE_5/ QUEUE_10/ QUEUE_20; Can't be passed together with price
modifyId	INT	NO	User-defined modification identifier, returned as-is in the response. Optional; not validated for uniqueness.
reduceOnly	STRING	NO	See notes below for behavior.
recvWindow	LONG	NO
timestamp	LONG	YES

• Either orderId or origClientOrderId must be sent, and the orderId will prevail if both are sent.
• Both quantity and price must be sent, which is different from dapi modify order endpoint.
• When the new quantity or price doesn't satisfy PRICE_FILTER / PERCENT_FILTER / LOT_SIZE, amendment will be rejected and the order will stay as it is.
• However the order will be cancelled by the amendment in the following situations:
  • when the order is in partially filled status and the new quantity <= executedQty
  • When the order is GTX and the new price will cause it to be executed immediately
• One order can only be modfied for less than 10000 times
• modifyId is an optional user-defined identifier passed through as-is; the server does not validate its uniqueness. If omitted, it is not included in the response.
• reduceOnly behavior:
  • false or omitted: behave as today — min_notional is enforced on the modified order.
  • true and the original order's reduceOnly attribute is also true (consistent): the min_notional check is skipped on the modified order, matching placement semantics.
  • true but the original order's reduceOnly attribute is false (inconsistent): the modify request is rejected with error code -5047, "The original order is not a reduce-only order".
  • reduceOnly is used purely for validation — passing true does not change the original order's reduceOnly attribute; that flag remains whatever it was set to at placement time.

Response Example

{
 	"orderId": 20072994037,
 	"symbol": "BTCUSDT",
 	"pair": "BTCUSDT",
 	"status": "NEW",
 	"clientOrderId": "LJ9R4QZDihCaS8UAOOLpgW",
 	"modifyId": 1,                     //user-defined modification identifier, only returned if provided in the request
 	"price": "30005",
 	"origQty": "1",
 	"executedQty": "0",
 	"cumQty": "0",
 	"timeInForce": "GTC",
 	"type": "LIMIT",
 	"reduceOnly": false,
 	"closePosition": false,
 	"side": "BUY",
 	"positionSide": "LONG",
 	"stopPrice": "0",
 	"workingType": "CONTRACT_PRICE",
 	"priceProtect": false,
 	"origType": "LIMIT",
    "priceMatch": "NONE",              //price match mode
    "selfTradePreventionMode": "EXPIRE_MAKER", //self trading preventation mode
    "goodTillDate": 0,                 //order pre-set auot cancel time for TIF GTD order
 	"updateTime": 1629182711600
}