Update Orders

You can use the UpdateOrder endpoint to add, replace, or delete fields in any order created using the Orders API.

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 returns 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 an UpdateOrder request with a sparse Order object that contains the changes you want to make. 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's 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.

"order": {
  "version": 2,
  "line_items": [
    {
      "uid": "cookie_uid",
      "quantity": "5",
    }
  ]
}

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:

    "fields_to_clear": [
      "discounts"
    ]

The UpdateOrder endpoint uses dot notation to delete fields within arrays. The dot notation path starts 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 the example order:

"fields_to_clear": [
     "line_items[small_coffee_uid]"
]

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:

"fields_to_clear": [
     "line_items[small_coffee_uid].applied_discounts[dollar_off_coffee_uid]"
]

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.