Update Orders
You can use the UpdateOrder endpoint to add, replace, or delete fields in any order created using the Orders API.
Note
Currently, the UpdateOrder
endpoint cannot update orders made in the Square Point of Sale application.
Your UpdateOrder
request must set the order
field with a sparse Order
object that includes the fields you want to update or add. This sparse Order
object must also have the version
field set to the current version of the order or your request throws an error. You can get the most recent version number by retrieving the order you want to update before calling UpdateOrder
.
The following example shows an UpdateOrder
request body with a version number and a new field to add:
Use the following cURL command to create the example order that you use in the rest of this topic:
To add a field to an order, send a request to UpdateOrder
with a sparse Order
object that contains the changes you want to make to your order. Your sparse Order
requires the following:
The most recent version number.
The field you want to add.
An idempotency key.
The following request adds an additional line item to an order with the given UID:
To replace a field, you need to send a request to the UpdateOrder
endpoint. Your request requires the following:
The most recent version number.
The ID of the field you want to replace if it is part of an array.
Any field details you want to add or replace.
For example, the following request updates the quantity of the cookie added in the previous example. Note that the order version is now 2
.
To delete a field in an order, you need to send a request to the UpdateOrder
endpoint. Your request must specify:
The most recent version number in the sparse
Order
object.The fields you want to delete in the
fields_to_clear
array.
For example:
You can identify fields to delete by listing them in the fields_to_clear
array. For example, setting fields_to_clear
as follows deletes all the items under discounts:
The UpdateOrder
endpoint uses dot notation to delete fields within arrays. The dot notation path starts from within the Order
object.
Access specific elements in an array by identifying the UID in brackets.
For example, setting fields_to_clear
as follows accesses the coffee line item in our example order:
You can then use dot notation to access fields within that specific element in the array.
For example, setting fields_to_clear
as follows deletes the $1 discount applied to the coffee line item:
In this example, the discount no longer applies to the line item; however,
the discount is still listed in the order in the order-level discounts
field.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.