Clear API Object Fields

The REST API architecture doesn't define an update request that clears a field value in a resource. As the Square API platform has grown, it has used several field-clearing mechanisms. As a result, your field-clearing code couldn't be standardized across all Square APIs. Starting with the 2022-09-21 version of the Square API, you can request field clearing in resources by using the new standard method described in this topic for any Square API objects that supports field clearing.

The Square API supports the sparse update of resources. Supporting sparse updates means that a Square update endpoint allows a client to PUT a copy of the resource that contains only the fields the client wants to change. The resource in the update request body is then merged with the server resource and only the sent field values (the version and updated_at fields are updated).

You don't need to include required fields in an update request as long as their values are already set on the server resource. You can include the fields on a change request if you want to update their values but you cannot clear the required field values.

What happens when you want to do a sparse update to request a value change that clears the existing value without replacing it with a new value? If you omit the field from the resource in the request body, the server resource field isn't modified. To clear a field value, you add the field to the resource in the request body but set the field value to null. When this update request is complete, the server has merged the field by clearing the existing value. Note that the new field value isn't an empty string. It's actually nothing at all (null).

All JSON data types can be cleared by setting their value to null. Square makes an exception for individual array elements in the Orders API and Invoices API. For an example of this method and its replacement, see Delete elements from array fields.

The following Square API objects support field clearing using one of the methods in this topic:

• Customer
• Order
• Location
• Invoice
• Subscription
• TeamMember
• Vendor

These API objects now support the standard null method. Any current API object that isn't in this list doesn't support field clearing at this time. Square is moving toward making all API objects support field clearing with the null method.

To signal that you intend to clear field values with a null in the request, you need to add a special HTTP header.

Starting with the 2022-09-21 version of the Square API, update endpoints support an X-Clear-Null: true HTTP header to indicate an update request containing a null field update. Add this header to update requests that clear field values. To minimize the impact of this change, the following update endpoints continue to use null to clear fields without the header:

• UpdateSubscription
• UpdateTeamMember
• BulkUpdateTeamMembers
• UpdateVendor
• BulkUpdateVendors

If you're using one of these endpoints, the X-Clear-Null header is optional and fields are still cleared. Square is moving toward treating null values as field clearing values. At this time, if you want to clear fields with a null value, you need to use the header in these endpoints.

In the following example, a Locations API sparse update request is specifying that the null field is cleared. All other location fields in the server resource are unchanged after this request is complete.

curl https://connect.squareupsandbox.com/v2/locations/L911449RQ1GFS \
 -X PUT \
 -H 'Square-Version: 2022-07-20' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'X-Clear-Null: true' \
 -d '{
   "location": {
     "coordinates": null
   }
 }'

The Orders API and Invoices API support deleting elements from array fields as long as the elements can be accessed using a uid index (for example, Order line_items and Invoice payment_requests). The new pattern for deleting an element from an array is relying on the uid and remove special fields. The following example uses the Orders API. To remove the Small Coffee item from the example order, the following would have been provided in the request payload:

'{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "version": "{CURRENT_VERSION_NUMBER}"
    },
    "fields_to_clear": [
      "line_items[small_coffee_uid]"
    ]
 }'

With the new pattern, the fields_to_clear object is de-emphasized in favor of a different type in the line_items array. The object consists of two fields:

• uid - This existing field contains the index of the individual line item to be cleared.
• remove - This new field indicates that the line item is to be removed.

For each array element that you want to clear, replace the element with the following in the line_items array:

       {
         "uid": "{element_uid}",
         "remove": true
       }

If you set the value of the remove field to anything except true, the request is treated as a non-operation. If you exclude the remove field, the request is treated as a sparse update.

To enable this new feature, you also need to specify the X-Clear-Null header as true as shown in the example:

curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
 -X PUT \
 -H 'Square-Version: 2022-05-12' \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'X-Clear-Null: true' \
 -d '{
   "idempotency_key": "{UNIQUE_KEY}",
   "order": {
     "version": {CURRENT_VERSION_NUMBER},
     "line_items": [
       {
         "uid": "{small_coffee_uid}",
         "remove": true
       }
     ]
   }
 }'