An overview of custom attributes, a lightweight way to include additional properties in a Square data model.
Developer Tools

Custom Attributes Overview Beta release
This is pre-release documentation for an API in public beta and is subject to change.

Custom attributes are a lightweight way to include additional properties in a Square data model. You can use custom attributes to extend Square’s data model to make it more specific to the business problem you are trying to solve. Custom attribute definitions are scoped to the seller, the application that defined them, and the parent resource type. To create a custom attribute for a seller, you need the following:

  • To be the owner of the custom attribute definition or the custom attribute definition's visibility field must be set to VISIBILITY_READ_WRITE_VALUES.

  • To be authorized by the seller (OAuth).

  • To have {RESOURCE}_WRITE permission for the resource, such as CUSTOMER_WRITE access for a given customer. To create a custom attribute definition, you only need authorization from a seller.

Important

Custom attributes are intended to store additional information about a resource or associations with an entity in another system. Do not 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.

The following APIs currently support custom attributes:

You can use custom attributes in a number of scenarios, such as when a seller has certain attributes they want to capture that are not native to the Square data model. For example, a vet clinic could store pet names, pet breeds, and pet ages for each customer using several custom attributes.

There are five custom attribute terms you need 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 is 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 is unique to each application and seller. The key allows you to define a custom attribute for any seller you work with. You can use the custom attribute key to access the custom attribute definition for any seller you work with. For example, suppose you create a custom attribute definition for “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.

  • Custom attribute. 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.

  • 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:

  • The Retrieve{ResourceType} and List{ResourceTypes} endpoint responses do not include custom attributes values. Use the custom attributes endpoint that is specific to the API you are working with to list the available custom attributes.

  • 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 do not 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.

For a high-level understanding of how to work with custom attributes, it is 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

Important

For any Square API you work with, the Retrieve{ResourceType} and List{ResourceTypes} endpoint responses do not include custom attributes.

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

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

  • VISIBILITY_HIDDEN (default)

  • VISIBILITY_READ_ONLY

  • VISIBILITY_READ_WRITE_VALUES


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

Custom attribute definition Custom attribute
Visibility setting READ WRITE READ WRITE
VISIBILITY_HIDDEN No No No No
VISIBILITY_READ_ONLY Yes No Yes No
VISIBILITY_READ_WRITE_VALUES Yes No Yes Yes

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.

Note

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.

The schema field of the custom attribute definition references a Square JSON schema that specifies the type information for a custom attribute value. For more information about the schema field, see Specifying the schema.

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

  • String. A string with up to 1000 UTF-8 characters. Empty strings are allowed.

  • Number. A string representation of an integer or decimal with up to 5 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.

  • Boolean. A true or false value.

  • PhoneNumber. A string representation of a phone number in E.164 format. For example, +17895551234.

  • Email. An email address consisting of ASCII characters that matches the regular expression for the HTML5 email type.

  • Date. A date in the ISO 8601 format: YYYY-MM-DD.

  • DateTime. A date and time in the ISO 8601 format, which represents the date and time by starting with the year, followed by the month, day, hour, minutes, seconds, and milliseconds. For example, '2022-07-10 15:00:00.000'.

  • Duration. A duration as defined by the ISO 8601 ABNF.

  • Address. An Address object. For information about Address fields, see Working with Addresses.

  • Selection. A selection from a set of named values specified in the custom attribute definition.

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 higher. For example, if your read request asks for version 5, you get data from version 5 or higher. If you do not specify a version in your request, you could get a lower version containing stale data if the current version has not been replicated to the data store you are reading from. Most replication typically completes quickly, but to ensure consistency, you should provide a value for the version field when reading data.

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.

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