Update Orders

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

Link to section

Sparse Order objects

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:

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}"
            }
          ]
        }
      ]
    }
  }'

Link to section

Example order

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

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"
        }
      ]
    }
  }'

Link to section

Adding fields

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:

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"
          }
        }
      ]
    }
  }'

Link to section

Replacing fields

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.

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

Link to section

Deleting fields

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:

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}"
    ]
  }'

Link to section

Identifying fields 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:

    "fields_to_clear": [
      "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:

"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.