Update Orders

Applies to: Orders API

Learn how to update orders by using sparse objects in an update request.

Use the UpdateOrder endpoint to add, update, or clear properties in an order created using the Orders API. Property values calculated by Square cannot be updated.

To update an order, your request should only include the properties that you want to add, update, or clear. This is known as a sparse order request. Unchanged and immutable properties are ignored by the update.

The Orders API uses optimistic concurrency to ensure that any update your application makes to an order doesn't overwrite a change made by another application. Your request must include the order.version property. version must be set to the current version of the order or your request returns an error. You can get the current version number by retrieving the order to be updated immediately before calling UpdateOrder.

The following example shows request to update an order with a new modifier that adds cream to a coffee. The UpdateOrder request body has the current version number and a new modifiers property:

Use the following cURL command to create the example order that you use in subsequent sections:

To add a property to an open 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 current version number.
• The property you want to add.
• A new idempotency key.

The following request adds an additional line item to an order with the given UID:

To update a property, you need to send a request to the UpdateOrder endpoint. Your request requires the following:

• The current version number.
• The uid of the property you want to update if it's part of a list.
• Any property details you want to add or update.

For example, the following request updates the quantity of the cookie added in the previous example. Five cookies are now on the order.

The previous example of adding a property incremented the order version, which is now 2.

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

Line item properties such as line_items[].name or line_items[].base_price can be ad hoc or they can be derived from a referenced catalog item variation. Derived properties are overridden in an update request when your application provides a new value in the request. If you update the base price of a line item, Square recalculates all the numeric properties where base_price is a calculation input.

Square-calculated order properties are read-only and cannot be updated by your request. If you try to update a field such as order.net_amount_due_money or other calculated property, the property update requests are silently ignored.

In some cases, Square adds supporting catalog detail to line items that reference a Catalog object. If these details cannot be overridden, an attempt to update them results in an error. For example, the following update requests tries to change the quantity_unit.precision of the fractional quantity defined in the catalog for the Ektol line item:

Square returns the following error response indicating the precision value cannot be changed using the API:

{
    "errors": [
        {
            "code": "INVALID_VALUE",
            "detail": "Immutable field cannot be changed.",
            "field": "order.line_items[RHlv1L5q4LR1ldOWxwkk2B].quantity_unit",
            "category": "INVALID_REQUEST_ERROR"
        }
    ]
}

To clear a property in an order, you need to send a request to the UpdateOrder endpoint. Your request must specify:

• The current version number of Order object.
• The properties you want to clear in the fields_to_clear array.

For example:

You can specify the order properties to clear by listing them in the fields_to_clear array. For example, setting fields_to_clear as follows clears order.discounts and all of its properties:

{
    "fields_to_clear": [
      "discounts"
    ]
}

The UpdateOrder endpoint uses dot notation to clear properties within arrays. The dot notation path starts within the Order object.

Clear specific elements in an array of order properties by identifying a property UID in brackets. For example, setting fields_to_clear as follows clears the coffee line item in the example order:

{
  "fields_to_clear": [
     "line_items[small_coffee_uid]"
  ]
}

You can then use dot notation to access properties within that specific element in the array. For example, setting fields_to_clear as follows clears 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. None of the order's line items reference the discount, which effectively cancels the discount. In this case, it is a good idea to remove the discount property since it is no longer used.

If you try to clear a required property such as order.source, your request returns a 200 response, but the Orders API ignores the property in the request.

{
    "fields_to_clear": [
      "source",
      "customer_id"
    ]
}