Clear API Object Fields

Learn about standard field-clearing methods that allow you to clear a field from an object in a sparse update request.

Square provides various endpoints that allow you to update objects such as orders, payments, and customers. Some of these endpoints support sparse updates, which means that the request doesn't need to include an entire replacement object. Instead, it only needs to include the fields that you want to add, change, or clear (in addition to any fields required by the update operation). You cannot clear the value of a required field, though in some cases you can update its value.

After the update operation is completed, only the values of the specified fields are changed, along with the version and updated_at fields if applicable.

To clear a field in a sparse update request, include the field in your request and set the value to null. Don't confuse null with an empty string.

The following UpdateLocation example clears the coordinates field by specifying null as the field value. All other fields for this location are unchanged after the update operation is completed.

Fields that can be cleared depend on the object that you're updating. When field clearing is supported, null values can be used to clear any field data type. Note that some array elements in an order or invoice are cleared using the remove field instead of null.

Global support for null field clearing was added in Square API version 2022-09-21. Although some update endpoints might continue to support alternate field clearing methods, Square recommends using null field clearing when possible.

You should avoid mixing field clearing methods in a single request, which might result in unexpected behavior. For example, don't attempt to clear fields using null values and the fields_to_clear field in an UpdateOrder or UpdateInvoice request. However, using null values and the remove field in a single request is supported.

UpdateOrder requests that use null to clear fields must also include the X-Clear-Null header, as shown in the following example:

curl https://connect.squareupsandbox.com/v2/orders/{{ORDER_ID}} \
 -X PUT \
 -H 'Square-Version: 2024-06-04' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'X-Clear-Null: true' \
 -d '{
   "order": {
     "version": 3,
     "reference_id": null
   }
 }'

If this header is not included, Square ignores any null settings in the UpdateOrder request.

In Square API version 2023-08-16 and later, the X-Clear-Null: true header is optional for other update endpoints. For earlier versions, Square recommends setting this header when clearing fields.

The Orders API and Invoices API support removing an individual element from an array field when the element can be accessed using a uid index (for example, order line_items or invoice payment_requests). For each array element that you want to clear, specify the uid of the element and include the remove field set to true.

  ...
  {
    "uid": "{ELEMENT_UID}",
    "remove": true
  }
  ...

The remove field is a special field that indicates the intent to delete the specified array element. It isn't present on the object. Square ignores the remove field if the value isn't true. Requests that specify the uid but exclude the remove field are treated as sparse updates.

When using the remove field to delete an array element in an UpdateOrder request, you also need to specify the X-Clear-Null header as true, as shown in the following example:

curl https://connect.squareupsandbox.com/v2/orders/{{ORDER_ID}} \
 -X PUT \
 -H 'Square-Version: 2024-06-04' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'X-Clear-Null: true' \
 -d '{
   "order": {
     "version": {CURRENT_VERSION_NUMBER},
     "line_items": [
       {
         "uid": "{LINE_ITEM_UID}",
         "remove": true
       }
     ]
   }
 }'

If this header isn't included, Square ignores the remove field in the UpdateOrder request.

In Square API version 2023-07-20 and earlier, UpdateInvoice requests also require the X-Clear-Null header when using the remove field to delete array elements.