Applies to: Customer Custom Attributes API | Customer Groups API
Learn how to create and manage customer-related custom attribute definitions for Square sellers using the Customer Custom Attributes API.
A custom attribute definition specifies the key
identifier, visibility
setting, schema
data type, and other properties for a custom attribute. After the definition is created, the custom attribute can be set for customer profiles in the seller's Customer Directory. For more information about how customer-related custom attributes work, see Custom Attributes for Customers.
Custom attribute definitions are stored as a collection for a Square seller. Customer-related custom attribute definitions are accessed using the customers
segment in the endpoint URL.
.../v2/customers/custom-attribute-definitions
Note
The Customer Groups API also enables personalized customer experiences. For example, the API can be used to set the same label for a group of customer profiles.
A custom attribute definition is represented by a CustomAttributeDefinition object. The following is an example custom attribute definition that defines a "Favorite Drink" custom attribute of the String
data type:
{
"custom_attribute_definition": {
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 1,
"updated_at": "2022-05-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
The following fields represent core properties of a custom attribute definition:
Field | Description |
---|---|
key | The identifier for the definition and its corresponding custom attributes. This key is unique for the application and cannot be changed after the definition is created. If the requesting application isn't the definition owner, the value is a qualified key. A qualified key is the application ID of the definition owner followed by the key that was provided when the definition was created, in the following format: {application ID}:{key} .For custom fields created by sellers in the Customer Directory, the qualified key is square:{key} . |
name | The name for the custom attribute. This name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller. This field is required if visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES . |
description | The description for the custom attribute. This field is required if visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES . |
visibility | The access control setting that determines whether other applications (including Square products such as the Square Dashboard) can view the definition and view or edit corresponding custom attributes. Valid values are VISIBILITY_HIDDEN , VISIBILITY_READ_ONLY , VISIBILITY_READ_WRITE_VALUES . For more information, see Access control.Regardless of the visibility setting, all custom attribute data is visible to sellers when exporting customer data. |
schema | The data type of the custom attribute value. For more information, see Specifying the schema. The total schema size cannot exceed 12 KB. |
version | The version number of the custom attribute definition. The version number is initially set to 1 and incremented each time the definition is updated. Include this field in update operations to enable optimistic concurrency control and in read operations for strong consistency. |
Use the CreateCustomerCustomAttributeDefinition endpoint to create a custom attribute definition for a seller account. This operation makes the custom attribute available to customer profiles in the seller's Customer Directory. Note the following:
key
is the identifier for the definition and its corresponding custom attributes. The value must be unique for the application. It can contain up to 60 alphanumeric characters, periods (.
), underscores (_
), and hyphens (-
) and must match the following regular expression:^[a-zA-Z0-9\._-]{1,60}$
visibility
is the access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:VISIBILITY_HIDDEN
(default)VISIBILITY_READ_ONLY
VISIBILITY_READ_WRITE_VALUES
Sellers can view all custom attributes in exported customer data, including those set to
VISIBILITY_HIDDEN
.schema
is the data type of the custom attribute. For more information, see Specifying the schema.name
anddescription
are the name and description of the custom attribute. Each field can contain up to 255 characters.Both fields are required when
visibility
is set toVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. If provided,name
must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller. Seller-facing custom attributes should be given a friendly name and description.idempotency_key
is a unique ID for the request that can be optionally included to ensure idempotency.
The following example request defines a "Favorite Drink" custom attribute whose value can be a String
:
Create customer custom attribute definition
The following is an example response:
{
"custom_attribute_definition": {
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 1,
"updated_at": "2022-05-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
Now that the custom attribute definition is created, you can set the custom attribute for the seller's customers. For more information, see Create or update a customer custom attribute or Bulk create or update customer custom attributes.
After a custom attribute definition is created, Square invokes the customer.custom_attribute_definition.owned.created
and customer.custom_attribute_definition.visible.created
webhook events.
A seller account can have a maximum of 100 customer-related custom attribute definitions per application.
Note
To view your custom attributes in the Customer Directory, the visibility
setting for the definition must be VISIBILITY_READ_WRITE_VALUES
and the seller must make the field visible from the Configure Profiles page. The custom attribute name appears in the directory, but the description doesn't.
The data type of a custom attribute is specified by the schema
field of the definition. Square uses the schema
to validate the custom attribute value when it's assigned to a customer profile. The total schema size cannot exceed 12 KB. When setting the value of the custom attribute for a customer profile, the total value size cannot exceed 5 KB.
The following data types are supported for customer-related custom attributes:
String
Email
PhoneNumber
Address
Date
Boolean
Number
Selection
Note
Customer-related custom attributes don't support DateTime
or Duration
data types.
In a CreateCustomerCustomAttributeDefinition
request, the schema
field specifies a data type by referencing a JSON schema or meta-schema object hosted on the Square CDN.
For the data types in the following table, specify a $ref
value that references the corresponding schema object, as shown in the following snippet that references the String
data type:
{ "custom_attribute_definition": { ... "schema": { "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String" }, ... } }
Data type | Description |
---|---|
| A string with up to 1000 UTF-8 characters. Empty strings are allowed.
|
| An email address consisting of ASCII characters that matches the regular expression for the HTML5
|
| A string representation of a phone number in E.164 format. For example,
|
| An Address object. For information about
|
| A date in ISO 8601 format:
|
| A
|
| A string representation of an integer or decimal with up to 5 digits of precision. Negative numbers are denoted using a For numeric values that act as identifiers rather than representing a quantity (such as account numbers), you might consider using the
|
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 thehttps://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json
meta-schema hosted on the Square CDN.type
must bearray
.items
must include anames
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 thenames
field.uniqueItems
must betrue
.
The following example request creates a Selection
-type custom attribute definition that contains three named options and allows 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.
{
"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"
}
}
Use the UpdateCustomerCustomAttributeDefinition endpoint to update a custom attribute definition for a seller account. Only the following fields can be updated:
name
description
visibility
schema
for aSelection
data type
Only new or changed fields need to be included in the request. For more information, see Updatable definition fields.
Note the following about an UpdateCustomerCustomAttributeDefinition
request:
A custom attribute definition can be updated only by the definition owner.
The
key
path parameter is thekey
of the custom attribute definition.The
version
field can be optionally included to enable optimistic concurrency control. If included,version
must match the current version of the custom attribute definition; otherwise, the request fails with aCONFLICT
error. Square increments the version number each time the definition is updated.The
idempotency_key
is a unique ID for the request that can be optionally included to ensure idempotency.
The following example request updates the visibility
setting of a definition:
Update customer custom attribute definition
The following is an example response:
{
"custom_attribute_definition": {
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 2,
"updated_at": "2022-05-28T04:17:09Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-20T02:41:37Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
After a custom attribute definition is updated, Square invokes the customer.custom_attribute_definition.owned.updated
and customer.custom_attribute_definition.visible.updated
webhook events.
The UpdateCustomerCustomAttributeDefinition
endpoint can be used to update one or more of the following fields. The endpoint supports sparse updates, so only new or changed fields need to be included in the request. Square ignores custom attribute definition fields that are unchanged or read-only.
name
- The name of the custom attribute of up to 255 characters. Seller-facing custom attributes should be given a friendly name. The name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.description
- The description of the custom attribute of up to 255 characters. Seller-facing custom attributes should be given a friendly description.visibility
- The access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:VISIBILITY_HIDDEN
(default)VISIBILITY_READ_ONLY
VISIBILITY_READ_WRITE_VALUES
Changes to the
visibility
setting are propagated to corresponding custom attributes within a couple seconds. At that time, theupdated_at
andversion
fields of the custom attributes are also updated. ForVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
settings, bothname
anddescription
are required.All custom attributes are visible in the .csv file when the customer data is exported, including those set to
VISIBILITY_HIDDEN
. Sellers can generate this file using the Export Customers button in the Customer Directory.schema
- For aSelection
data type. Only changes to the named options and maximum number of selections are supported, as described in the following section. The totalschema
size cannot exceed 12 KB.
Did you know?
To simplify management, you might want to keep all definitions that use the same key synchronized across seller accounts. Therefore, if you change the definition for one seller, you should consider making the same change for all other sellers.
For a Selection
data type, you can update the maximum number of allowed selections and the set of predefined named options.
Note
Square validates custom attribute selections on upsert operations, so these changes apply only for future upsert operations. They don't affect custom attributes that have already been set on customer profiles.
The information you send in the UpdateCustomerCustomAttributeDefinition
request depends on the change you want to make:
To change the maximum number of allowed selections, include the
maxItems
field with the new integer value. The minimum value is 1 and cannot exceed the number of options in thenames
field.To change the set of predefined named options, include the
items
field with the completenames
andenum
arrays. The options in thenames
array map by index to the Square-assigned UUIDs in theenum
array, which are unique per seller. The first option maps to the first UUID, the second option maps to the second UUID, and so on.To add an option:
- Add the name of the new option at the end of the
names
array. New options must always be added to the end of the array. - Don't change the
enum
array. Square generates a UUID for the new option and adds it to the end of theenum
array.
- Add the name of the new option at the end of the
To reorder the options:
Change the order of the names in the
names
array.Change the order of the UUIDs in the
enum
array so that the order of the UUIDs matches the order of the corresponding named options.Note that the order might not be respected by all UIs.
To remove an option:
- Remove the name of the option from the
names
array. - Remove the corresponding UUID from the
enum
array.
- Remove the name of the option from the
The following example UpdateCustomerCustomAttributeDefinition
request adds two new options by adding the names at the end of the names
array.
Update customer custom attribute definition
The following example response includes the UUID that Square generated for the new X-Small
and X-Large
options:
{
"custom_attribute_definition": {
"key": "shirt-size",
"name": "Default shirt size",
"description": "The default shirt size ordered by the customer.",
"version": 2,
"updated_at": "2022-05-27T15:55:42Z",
"schema": {
"$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
"maxItems": 1,
"type": "array",
"uniqueItems": true,
"items": {
"names": [
"Small",
"Medium",
"Large",
"X-Small",
"X-Large"
],
"enum": [
"a5fc0632-b5cf-4855-af35-7bfc88bdc9f5",
"e875633f-a5d8-4872-aef4-6b96fba78c3e",
"30528ff7-b11b-425a-aa11-26ff5cf1996f",
"18fb06bd-9be0-4709-9c7f-737a1fd40e44",
"6031c1b2-d749-4c78-9c40-ae5472ed2e03"
]
}
},
"created_at": "2022-05-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
Use the ListCustomerCustomAttributeDefinitions endpoint to list the custom attribute definitions from a seller account. Note the following:
The
limit
query parameter optionally specifies a maximum page size of 1 to 100 results. The default limit is 20.If the results are paged, the
cursor
field in the response contains a value that you can send with thecursor
query parameter to get the next page of results.
The following example request includes the limit
query parameter:
List customer custom attribute definitions
When all pages are retrieved, all custom attribute definitions created by the requesting application are included in the results. The key
for these definitions is the key
that was provided when the definition was created.
Custom attribute definitions created by other applications are included if their visibility
is VISIBILITY_READ_ONLY
or VISIBILITY_READ_WRITE_VALUES
. The key
for these definitions is a qualified key.
Custom attributes created in the Customer Directory are called custom fields in the UI and they're always set to VISIBILITY_READ_WRITE_VALUES
.
The following is an example response:
{
"custom_attribute_definitions": [
{
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 2,
"updated_at": "2022-05-28T04:17:09Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-22T21:30:16Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "entity-id",
"name": "Entity ID",
"version": 1,
"updated_at": "2022-05-30T09:44:42Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-30T09:44:42Z",
"visibility": "VISIBILITY_HIDDEN"
},
{
"key": "sq0idp-BuahoY39o1X-GPxRRUWc0A:businessEmail",
"name": "Work email",
"description": "Work email address",
"version": 1,
"updated_at": "2022-06-14T03:23:15Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Email"
},
"created_at": "2022-06-22T03:23:15Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "square:0460be56-6783-4482-8d55-634f9ae61684",
"name": "Is Premium Member",
"description": "Created via the Customers Directory.",
"version": 1,
"updated_at": "2021-10-02T23:15:51Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean"
},
"created_at": "2021-10-02T23:15:51Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
],
"cursor": "ODmcskdO5tF0GTrPAPjlGQ...QxACXlOQYbdKq0FZ4LC"
}
The example response contains four custom attribute definitions:
"Favorite Drink" and "Entity ID" were created by the requesting application. Because "Entity ID" is set to
VISIBILITY_HIDDEN
, it's returned only when requested by the definition owner."Work email" was created by another third-party application. Note that the qualified key includes the ID of the application that created the custom attribute definition.
"Is Premium Member" was created by the seller in the Customer Directory. For first-party Square products, the
application_id
issquare
.
If no custom attribute definitions are found, Square returns an empty response.
{}
Use the RetrieveCustomerCustomAttributeDefinition endpoint to retrieve a custom attribute definition using the key
. Note the following:
The
key
path parameter is thekey
of the custom attribute definition.If the requesting application is the definition owner, use the
key
that was provided when the definition was created.If the requesting application isn't the definition owner, use the qualified key. The
visibility
of the definition must beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.Custom attributes created in the Customer Directory are called custom fields in the UI and they're always set to
VISIBILITY_READ_WRITE_VALUES
.
The
version
query parameter is optionally used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a400 BAD_REQUEST
error.
The following is an example request:
Retrieve customer custom attribute definition
Note
Square also returns custom attribute definitions for RetrieveCustomerCustomAttribute
or ListCustomerCustomAttributes
requests if you set the with_definition
or with_definitions
query parameter to true
. For more information, see Retrieve a customer custom attribute or List customer custom attributes.
The following is an example response:
{
"custom_attribute_definition": {
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 1,
"updated_at": "2022-05-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-05-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
If the custom attribute definition isn't found, Square returns an errors
field that contains a 404 NOT_FOUND
error.
Use the DeleteCustomerCustomAttributeDefinition endpoint to delete a custom attribute definition from a seller account. Note the following:
A custom attribute definition can be deleted only by the definition owner.
The
key
path parameter is thekey
of the custom attribute definition.Deleting a custom attribute definition also deletes the corresponding custom attribute from all customer profiles in the seller's directory.
The following is an example request:
Delete customer custom attribute definition
If successful, Square returns an empty object.
{}
After a custom attribute definition is deleted, Square invokes the customer.custom_attribute_definition.owned.deleted
and customer.custom_attribute_definition.visible.deleted
webhook events.