Learn how to update orders and how to specify sparse objects in an update request to add, update, and delete fields.
Orders API

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:

Update Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "version": 1,
      "line_items": [
        {
          "catalog_object_id": "{COFFEE_ITEM_ID}",
          "modifiers": [
            {
              "catalog_object_id": "{SMALL_MODIFIER_ID}"
            }
          ]
        }
      ]
    }
  }'

Use the following cURL command to create the example order that you use in the rest of this topic:

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "line_items": [
        {
          "uid": "{small_coffee_uid}",
          "name": "Small Coffee",
          "quantity": "1",
          "base_price_money": {
            "amount": 500,
            "currency": "USD"
          },
          "applied_discounts": [
            {
              "uid": "{dollar_off_coffee_uid}",
              "discount_uid": "dollar_discount_uid"
            }
          ]
        }
      ],
      "discounts": [
        {
          "name": "Sale - $1.00 off",
          "uid": "{dollar_discount_uid}",
          "amount_money": {
            "amount": 100,
            "currency": "USD"
          },
          "scope": "LINE_ITEM"
        }
      ]
    }
  }'

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:

Update Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "version": 1,
      "line_items": [
        {
          "uid": "{cookie_uid}",
          "quantity": "2",
          "name": "COOKIE",
          "base_price_money": {
            "amount": 200,
            "currency": "USD"
          }
        }
      ]
    }
  }'

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:

Update Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "version": "{CURRENT_VERSION_NUMBER}"
    },
    "fields_to_clear": [
      "{FIELDS OR ARRAYS TO DELETE}"
    ]
  }'

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.

We've made improvements to our docs.
Prefer the old format?