Update an Order
The method PATCH /orders/
enables you to provide a set of new properties to an existing order, such as changing the price or amount. Hence, you no longer need to cancel and place a new order when you want to change any of its modifiable properties.
To use this endpoint effectively, be cautious with the following constraints:
- Account must have an available balance: To update an order, your account must maintain an available balance in the given currency in addition to the already locked balance. The service calculates the available balance as the total balance minus the locked balance, the amount locked away in open orders. For a more detailed understanding of balances, refer to the section, Get Account Balance.
- Order's direction and type are unchangeable: You cannot update an order's direction or type. Instead, an equivalent order of the same type and mode replaces your updated order.
- Not all orders are modifiable: Market, completed, or cancelled orders are unavailable for updates. In the event the order to replace is completed or cancelled while the Trading Engine is processing it, the service creates the replacement order.
- Configure a valid update: Several combinations of properties to modify are not possible. For example, you can update the
minor
parameter only on un-triggered Stop-Loss Orders, or you cannot set a stop price on a Limit Order. - Updates do not preserve client-supplied IDs: The parameter
origin_id
is unique for each order, whether replacement or original. Replacement orders do not inherit it from the original order. If you don't provide an ID in your update request body, then none is set in the replacement order.
You have two ways to specify the identifier of the order to update:
- A path parameter: Use the Bitso-supplied ID.
- A query parameter: Use either the Bitso-supplied or user-supplied ID.
HTTP Request
- PATCH https://api-stage.bitso.com/api/v3/orders/{oid}
- PATCH https://api-stage.bitso.com/api/v3/orders?oid={oid}
- PATCH https://api-stage.bitso.com/api/v3/orders?origin_id={origin_id}
Path Parameters
Use the following path parameter to specify the order:
Parameter | Description | Required |
---|---|---|
oid | Specifies the Bitso-supplied identifier of the order to update. | No |
Query Parameters
However, if you prefer to use a query parameter, use either of the following ones to identify the order:
Parameter | Description | Required |
---|---|---|
oid | Specifies the Bitso-supplied identifier of the order to update. | No |
origin_id | Specifies by origin ID (client-supplied ID) the order to update. | No |
Body Parameters
Body parameters must be JSON encoded and precisely the same as the JSON payload used to construct the signature:
Parameter | Description | Required |
---|---|---|
major | The amount of the major currency to update. | No. See callout below. |
minor | The amount of the minor currency to update, the order's value. Use this parameter only with Stop-Loss Orders. You must specify an order in terms of either major or minor , never both. | No. See callout below. |
origin_id | The order's client-supplied, unique ID. Valid character set: a to z (lower and uppercase), 0 to 9 , and underscore, _ . The dash character, - , is not allowed. | No. See callout below. |
price | The price in minor at which to buy or sell the amount, the rate of the major/minor combination. | No. See callout below. |
stop | The price per unit of major at which to stop and place the order. Use this parameter only with Stop Orders. | No. See callout below. |
The request body cannot be empty.
Your request must include at least one of the possible body parameters.
JSON Response Payload
The endpoint returns a JSON object representing the replacement order. This object includes the following field:
Field Name | Description | Type |
---|---|---|
oid | The replacement order's unique ID. | String |
The following response object exemplifies the JSON object returned:
{
"success": true,
"payload": {
"oid": "qlbga6b600n3xta7"
}
}
Updated 29 days ago