Learn how to clear Square API resource fields using a standard method for all clearable fields.
Build Basics

Clear API Object Fields

The REST API architecture does not 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 could not 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 do not 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 is not 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 is not an empty string. It is 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 is not in this list does not support field clearing at this time. Square is moving toward making all API objects support field clearing with the null method.

Note

The current field clearing methods of various Square APIs can be used for the present. In the current implementation, you must define which method you are using. The server-side behavior for new API versions will, by default, process your update requests using these clearing methods.

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

Note

You should not mix the use of the fields_to_clear syntax with the null field value syntax. The result of such a mixed syntax is that the Square endpoint might respond with unexpected behavior.

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.

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:

Note

You should not mix the use of the fields_to_clear syntax with the remove field syntax. The result of such a mixed syntax is that the Square endpoint might respond with unexpected behavior.

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:

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:

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.