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 GetResourceType and ListResourceType 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 these changes 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.

Custom attribute workflow Permalink Get a link to this section

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 GetResourceType and ListResourceType endpoint responses do not include custom attributes.

Access control Permalink Get a link to this section

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 first-party 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

Accessing custom attributes owned by other applications Permalink Get a link to this section

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.

Supported data types Permalink Get a link to this section

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})?$. 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.

Strong consistency for reads Permalink Get a link to this section

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.

Subscribing to webhooks Permalink Get a link to this section

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

  • Public webhook event notifications apply to any custom attribute definition that has its visibility field set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. An application can subscribe to a public event notification to receive event notifications when an update is made (by any application) to custom attributes that your application has read access to. Public event notifications include all the custom attributes created by any application with visibility set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

  • Non-public webhook event notifications are available only to the owner of the custom attribute definition. This type of event notification notifies the owner of any changes to a custom attribute definition or to a custom attribute.

Event notification scenarios Permalink Get a link to this section

You can subscribe to webhook event notifications that occur when a custom attribute or custom attribute definition changes. There are three variables that influence webhook event notification behavior. These variables are custom attribute definition ownership, the visibility setting for the custom attribute definition, and whether the event notification is public or non-public.

The following scenarios show how these variables impact event notifications:

Ownership. Square is the owner (custom attribute definition created using the Seller Dashboard).
Visibility. READ or READ_WRITE
Public and non-public webhooks. Public webhooks go to any subscribing application. Non-public webhooks are not relevant in this scenario.

Ownership. The application is the owner.
Visibility. READ or READ_WRITE
Public and non-public webhooks. Public webhooks go to any subscribing application. Non-public webhooks are sent to the owner application. In this scenario, the owner application receives two notices if it subscribes to both the public and non-public webhooks, so it does not need to subscribe to the public webhook.

Ownership. Not your application.
Visibility. READ or READ_WRITE
Public and non-public webhooks. Public webhooks go to any subscribing application. Non-public webhooks are not sent to your application.

Ownership. Not your application.
Visibility. Hidden
Public and non-public webhooks. No public webhooks are sent. Because your application is not the owner, it does not receive a non-public webhook.

Ownership. The application is the owner.
Visibility. Hidden
Public and non-public webhooks. No public webhook is sent. Because your application is the owner, it receives a non-public webhook.

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