An overview of custom attributes, which are a lightweight way to include additional properties in the 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 extend the Square data model and add new properties to some objects, thereby making them more specific to the business problem you are solving. 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 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 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 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

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{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 do not include custom attribute values. Use the custom attributes endpoint that is specific to the API you are 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 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.

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.

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.

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

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 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 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 is 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 type
Description
$ref value
StringA string with up to 1000 UTF-8 characters. Empty strings are allowed.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
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.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
BooleanA true or false value.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean
PhoneNumberA string representation of a phone number in E.164 format. For example, +17895551234.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.PhoneNumber
EmailAn email address consisting of ASCII characters that matches the regular expression for the HTML5 email type.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Email
DateA date in ISO 8601 format: YYYY-MM-DD.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Date
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.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.DateTime
DurationA duration as defined by the ISO 8601 ABNF. For example, "P3Y6M4DT12H30M5S".https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Duration
AddressAn Address object. For information about Address fields, see Working with Addresses.https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Address
SelectionA selection from a set of named values specified in the custom attribute definition.See 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 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.

Create Customer Custom Attribute Definition
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
curl https://connect.squareupsandbox.com/v2/customers/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "key": "shirt-size",
      "schema": {
        "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
        "maxItems": 1,
        "type": "array",
        "uniqueItems": true,
        "items": {
          "names": [
            "Small",
            "Medium",
            "Large"
          ]
        }
      },
      "name": "Default shirt size",
      "description": "The default shirt size ordered by the customer.",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
{
  "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 do not specify a version in your request, you could get an earlier 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.