Custom Attributes

Learn about custom attributes, which are a lightweight way to include additional properties in the Square data model.

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:

• Bookings
• Customers
• Locations (beta)
• Merchants (beta)
• Orders (beta)

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.

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:

• Custom Attributes for Bookings
• Custom Attributes for Customers
• Custom Attributes for Orders
• Custom Attributes for Locations
• Custom Attributes for Merchants

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:

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.

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.

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 https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json 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.

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.

{
  "custom_attribute_definition": {
    "key": "shirt-size",
    "name": "Default shirt size",
    "description": "The default shirt size ordered by the customer.",
    "version": 1,
    "updated_at": "2022-05-20T02:41:37Z",
    "schema": {
      "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
      "maxItems": 1,
      "type": "array", 
      "uniqueItems": true,
      "items": {
        "names": [
          "Small",
          "Medium",
          "Large"
        ],
        "enum": [
          "a5fc0632-b5cf-4855-af35-7bfc88bdc9f5",    // UUID for "Small"
          "e875633f-a5d8-4872-aef4-6b96fba78c3e",    // UUID for "Medium"
          "30528ff7-b11b-425a-aa11-26ff5cf1996f"     // UUID for "Large"
        ]
      }
    },
    "created_at": "2022-05-20T02:41:37Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

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.

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.