Custom Attributes Overview

Custom attributes are a lightweight way to extend the Square data model and add new properties to some objects, thereby making them more specific to the business problem you're solving. You can use custom attributes in a number of scenarios, such as when a seller has certain attributes they want to capture that aren't native to the Square data model. For example, a veterinary clinic could store pet names, breeds, and ages for each customer using several custom attributes or a restaurant could use custom attributes to denote table numbers and server names for in-person orders.

The following APIs currently support custom attributes:

There are five custom attribute terms to be familiar with:

  • Custom attribute definition - This specifies the characteristics of a custom attribute. It defines the data type, schema, addressable endpoints, and configuration of the custom attribute. The custom attribute definition uses the Square custom attribute schema field to specify the type information for a custom attribute. Every custom attribute has a definition that's associated with a specific seller. After a custom attribute is defined, the values for that attribute are available to the seller. You can also specify the visibility of the custom attribute for the seller and to other applications.
  • Custom attribute key - Every custom attribute definition has a key that's unique to each application and seller. The key allows you to define and access a custom attribute for any seller you work with. For example, suppose you create a custom attribute definition called favorite-color. If you work with several sellers, you could use the definition to create Favorite Color custom attributes for each seller. You use the custom attribute key and the parent resource ID to access the custom attribute. Some custom attribute APIs allow you to work with seller-defined custom attributes. When doing so, you use a qualified key.
  • Custom attribute - This is the entity containing the custom attribute data and references to the custom attribute definition that defines it.
  • Custom attribute value - This value is used to distinguish between the custom attribute itself and its value.
  • Custom attribute visibility - When you create a custom attribute definition, you specify the visibility of the custom attribute. This determines not only whether other applications and sellers can see the custom attribute, but it also determines what actions other applications can take regarding the custom attribute. Visibility is described in greater detail in the following sections.

There are also several behaviors that apply to custom attributes that you should know:

  • For any Square API you work with, the Retrieve{ResourceType} and List{ResourceTypes} endpoint responses don't include custom attribute values. Use the custom attributes endpoint that's specific to the API you're working with to list the available custom attributes.
  • If the visibility of a custom attribute definition is updated, the change is propagated within a few seconds to its corresponding custom attributes.
  • If a custom attribute definition is deleted, all corresponding custom attributes are also deleted.
  • Square validates custom attribute selections on upsert operations, so any changes that you make to the definition schema apply only to future upsert operations. They don't affect custom attributes that have already been set. For example, a selection definition can be changed from allowing a maximum number of three items to only allowing a maximum number of one item. Any value with more than one item remains in place and can still be retrieved, but the value cannot be saved until the value is changed to match the current custom attribute definition.


Custom attributes are intended to store additional information about a resource or associations with an entity in another system. Don't use custom attributes to store any PCI data (such as card details). PII data is supported in custom attribute values, but applications that create or read this data should observe applicable privacy laws and data regulations such as avoiding logging custom attribute data when a deletion request is received.

Link to section

Custom attribute workflow

For a high-level understanding of how to work with custom attributes, it's helpful to focus on three common workflows:

  • Define the properties and create a custom attribute definition for a seller.
  • Set custom attributes.
  • Assign custom attribute values.

For details about how to perform these actions for each of the supported APIs, see the following:

Link to section

Access control

The application that creates a custom attribute definition is the definition owner. The definition owner always has READ and WRITE permissions to the definition and all instances of the corresponding custom attributes.

The visibility setting specified by a custom attribute definition determines how other applications can access the definition and corresponding custom attributes:

  • VISIBILITY_HIDDEN (default) - The definition and corresponding custom attributes are only visible to the definition owner.
  • VISIBILITY_READ_ONLY - Allows other applications to view the custom attribute definition and corresponding custom attributes.
  • VISIBILITY_READ_WRITE_VALUES - Allows other applications to set or delete the custom attribute.

The following table shows access control permissions for other applications that make calls on behalf of a seller, including Square products:

Custom attribute

Custom attribute
Link to section

Accessing custom attributes owned by other applications

To access custom attribute definitions created by other applications or their corresponding custom attributes, the following conditions must be true:

  • The visibility field of the definition must be set to one of the following:
    • VISIBILITY_READ_ONLY - Allows other applications to view the custom attribute definition and corresponding custom attributes.
    • VISIBILITY_READ_WRITE_VALUES - Additionally allows other applications to set or delete the custom attribute.


If the visibility of a custom attribute definition is updated, the change is propagated within a few seconds to its corresponding custom attributes.

If a custom attribute definition is deleted, all corresponding custom attributes are also deleted.

Link to section

Supported data types

The data type of a custom attribute is specified by the schema field of the custom attribute definition. Square uses the schema to validate the custom attribute value when it's assigned to a resource, such as a customer or location. All data types except Selection are specified using a simple URL reference to an object hosted on the Square CDN. For more information, see Selection data type.

Custom attributes support the following data types. Note that not all APIs support all the data types.

Data typeDescription$ref value
StringA string with up to 1000 UTF-8 characters. Empty strings are allowed.
NumberA string representation of an integer or decimal with up to five digits of precision that matches the following regular expression: ^-?[0-9]*(\.[0-9]{0,5})?$. This limit might vary by API. Negative numbers are denoted using a - prefix.
BooleanA true or false value.
PhoneNumberA string representation of a phone number in E.164 format. For example, +17895551234.
EmailAn email address consisting of ASCII characters that matches the regular expression for the HTML5 email type.
DateA date in ISO 8601 format: YYYY-MM-DD.
DateTimeA string representation of the date and time in the ISO 8601 format, starting with the year, followed by the month, day, hour, minutes, seconds, and milliseconds. For example, 2022-07-10 15:00:00.000.
DurationA duration as defined by the ISO 8601 ABNF. For example, "P3Y6M4DT12H30M5S".
AddressAn Address object. For information about Address fields, see Working with Addresses.
SelectionA selection from a set of named values specified in the custom attribute definition.See JSON meta-schema object.
Link to section

Selection data type (JSON meta-schema object)

For a Selection data type, the schema contains a $schema field that references a JSON meta-schema object, as well as additional fields. Note the following:

  • $schema references the meta-schema hosted on the Square CDN.
  • type must be array.
  • items must include a names array that contains strings representing the display names of the predefined options that can be selected. Note that the order of the options might not be respected by all UIs.
  • maxItems is an integer that represents the maximum number of allowed selections. Corresponding custom attributes can have zero or more selected values, up to the specified maximum. The minimum value is 1 and cannot exceed the number of options in the names field.
  • uniqueItems must be true.

The following call to the CreateCustomerCustomAttributeDefinition endpoint creates a Selection-type customer custom attribute definition. The definition contains three named options and allows for one selection.

Create customer custom attribute definition

The following is an example response. For each named option, Square generates a UUID and adds it to the enum field. The options in the names field map by index to the UUIDs in the enum field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.

These UUIDs are used to set the value of the custom attribute or update the option names.

Link to section

Strong consistency for reads

You can enforce strong consistency when reading a custom attribute by using the version field. When you set the version field on a custom attribute to a given value, you receive custom attribute data with that version or later. For example, if your read request asks for version 5, you get data from version 5 or later. If you don't specify a version in your request, you could get an earlier version containing stale data if the current version hasn't been replicated to the data store you're reading from. Most replication typically completes quickly, but to ensure consistency, you should provide a value for the version field when reading data.

Link to section

Subscribing to webhooks

Two types of webhook event notifications are generated for custom attributes:

  • .owned event notifications are sent when changes are made to custom attribute definitions and custom attributes that are owned by your application. A custom attribute definition is owned by the application that created it. A custom attribute is owned by the application that created the corresponding custom attribute definition.
  • .visible event notifications are sent when changes are made to custom attribute definitions and custom attributes that are visible to your application. These changes apply to:
    • All custom attribute definitions and custom attributes owned by your application.
    • All other custom attribute definitions or custom attributes whose visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.