Custom attributes store properties or metadata that can be used to simplify integration and synchronization or enable new personalization workflows. You can use the Customer Custom Attributes API to define custom attributes that can be associated with customer profiles, such as Favorite Drink, Occupation, Last Check-In Date, and Entity ID. You can also use the API to retrieve and manage seller-defined custom fields.
Watch the following video to see how the API works:
A custom attribute obtains a
visibility setting, allowed data type, and other properties from a custom attribute definition. This relationship is shown in the following diagram:
After a customer-related custom attribute definition is created for a Square seller account, the custom attribute can be set for customer profiles in the seller's Customer Directory.
You can use the Customer Custom Attributes API to extend the
Customer data model and associate seller-specific or application-specific information with customer profiles. For a high-level understanding of how you work with customer-related custom attributes, it's helpful to focus on three basic operations:
When you want to create a new customer-related custom attribute, you must first define its properties by calling
The following example request defines a Favorite Drink custom attribute. The
schema field indicates that the value of the custom attribute is a
Create customer custom attribute definition
key identifier and
visibility setting that you specify for the definition are also used by corresponding custom attributes. The
visibility setting determines the access level that other applications (including the Customer Directory and other Square products) have to the definition and corresponding custom attributes.
After the custom attribute definition is created, you can set the custom attribute for any customer profile in the seller's Customer Directory.
The following example
UpsertCustomerCustomAttribute request sets the Favorite Drink custom attribute using the
key. Note the following:
keyin the path is
favorite-drink, which is the same key specified by the definition.
valuein the request body sets the custom attribute value for the customer profile. This value must conform to the data type specified by the
schemafield in the definition (for this example, a
Upsert customer custom attribute
You can now retrieve the custom attribute to get the value that was set for the customer profile.
The following example
RetrieveCustomerCustomAttribute request retrieves the Favorite Drink custom attribute for a customer profile using the
Retrieve customer custom attribute
value field in the following example represents the custom attribute value:
You can include the
with_definition query parameter to return the corresponding custom attribute definition in the same call. For example, you might want to retrieve the definition to get the custom attribute's data type or name.
The Customer Custom Attributes API supports the following operations:
- Create a customer custom attribute definition
- Update a customer custom attribute definition
- List customer custom attribute definitions
- Retrieve a customer custom attribute definition
- Delete a customer custom attribute definition
- Create or update a customer custom attribute (upsert)
- Bulk create or update customer custom attributes (bulk upsert)
- List customer custom attributes
- Retrieve a customer custom attribute
- Delete a customer custom attribute
The data type of a custom attribute is specified in the
schema field of the custom attribute definition. For all data types except
Selection, this field contains a simple URL reference to a schema object hosted on the Square CDN.
Customer-related custom attributes support the following data types:
For information about defining the data type for a customer-related custom attribute, see Specifying the schema.
CreateCustomerCustomAttributeDefinition request is scoped to a specific seller. Creating a definition makes the corresponding custom attribute available to the customer profiles in the seller's Customer Directory.
To make the custom attribute available to other sellers, you must call
CreateCustomerCustomAttributeDefinition on behalf of each target seller. To do so when using OAuth, call this endpoint for each seller using their access token.
The following diagram represents two sellers using identical
favorite-drink custom attribute definitions to record their customers' favorite drink:
You can reuse the same
key for your custom attribute definition across sellers. The
key must be unique for your application but not for a given seller. However, if you provide a
name, it must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.
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.
visibility specified by a custom attribute definition determines how other applications that make calls on behalf of a seller can access the definition and corresponding custom attributes. This access control applies to third-party applications and Square products, such as the Customer Directory.
The following table shows the access permitted by each supported
- 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.
- Customer-related custom attributes set to
VISIBILITY_READ_ONLYaren't currently visible in the Customer Directory or Point of Sale application.
To access custom attributes or definitions owned by other applications, the following conditions must be true:
visibilityfield must be set to one of the following:
VISIBILITY_READ_ONLY- Allows other applications to view the definition and corresponding custom attributes.
VISIBILITY_READ_WRITE_VALUES- Additionally allows other applications to set the value of the custom attribute for customer profiles or delete the custom attribute from customer profiles.
The requesting application must use thefor the following requests:
To obtain a qualified key, call
ListCustomerCustomAttributes. These endpoints return qualified keys for custom attribute definitions and custom attributes that are owned by other applications and visible to your application. For more information, see List customer custom attribute definitions and List customer custom attributes.
You can subscribe to receive notifications for customer-related custom attribute events. Each event provides two options that allow you to choose when Square sends notifications:
.ownedevent 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.
.visibleevent 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_READ_WRITE_VALUES. This includes seller-defined custom attributes (also known as custom fields), which are always set to
Notification payloads for both options contain the same information.
Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:
Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These
.visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an
.owned event when you subscribe to the corresponding
.public events and replacement
.visible events apply to a different set of events. For more information, see Deprecated webhooks.
The following is an example
The following is an example
Note the following:
.visibleevents are available for webhook subscriptions starting in Square version
2022-08-17. The deprecated events are available starting in Square version
CUSTOMERS_READpermission is required to receive notifications about customer-related custom attribute events.
keyof the custom attribute definition or custom attribute in the notification is always the .
If you subscribe to the
.visibleoptions for the same event, Square sends both notifications for changes to custom attribute definitions and custom attributes owned by the subscribing application.
The value of the
data.idin the notification depends on the affected object:
- For custom attribute definition events,
data.idis the qualified key.
- For custom attribute events,
data.idis generated using the qualified key and the ID of the affected customer profile. This
data.idcannot be used directly with the Customer Custom Attributes API.
- For custom attribute definition events,
The following requirements, limitations, and other considerations apply when working with customer-related custom attributes:
Minimum Square version - Square version
2022-05-12or higher is required to work with the Customer Custom Attributes API.
Sensitive data - Custom attributes are intended to store additional information or store associations with an entity in another system. Don't use custom attributes to store any PCI data, such as credit card details. PII is supported in custom attribute values, but applications that create or read this data should observe applicable privacy laws and data regulations such as requesting the hard deletion of custom attribute data when a GDPR request for erasure is received. Never store secret-level information in a custom attribute. The use of custom attributes is subject to developers adhering to the Square API Data Policy Disclosures.
Unsupported data types - You can only create customer-related custom attribute definitions that specify a
schemafor a supported data type. The following data types aren't supported for customer-related custom attributes:
Search support in the Customers API - The
custom_attributefilter can be used with the SearchCustomers endpoint to search customer profiles by custom attribute. However, custom attributes aren't included in the search results. To retrieve or list custom attributes for a customer profile based on a search, you can call
ListCustomerCustomAttributesusing a customer ID from the result set. For more information, see Search by custom attributes.
Limits - A seller account can have a maximum of 100 customer-related custom attribute definitions per application.
Unique name - If the
visibilityof a customer-related custom attribute definition is
namemust be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller. This requirement is intended to help sellers differentiate between custom attributes that are visible in the Customer Directory and other Square products.
Maximum value for Number custom attributes - The absolute value of a
Number-type custom attribute cannot exceed
(2^63-1)/10^5, or 92233720368547.
OAuth permissions - Applications that use OAuth require
CUSTOMER_WRITEpermission to work with customer-related custom attributes. For more information, see OAuth API Overview and Customer Custom Attributes.
If a seller revokes the permissions of the application that created a custom attribute definition, or if the token expires, the application cannot access the definition or corresponding custom attributes until permissions are restored. However, the definition and custom attributes remain available to other applications according to the
Idempotency - Including an idempotency key in a request guarantees that the request is processed only once. The following endpoints allow you to specify an
Be sure to generate a unique idempotency key for each request. If an idempotency key is reused in requests to the same endpoint on behalf of the same seller, Square returns the response from the first request that was successfully processed using the key. Square doesn't process subsequent requests that use the same key, even if they contain different fields. For more information, see Idempotency.
The following migration notes apply to the Customer Custom Attributes API.
Deprecated in version: 2022-08-17
Retired in version: TBD
The following table lists deprecated webhook events and their replacements.
.visible event types introduced in Square version 2022-08-17 enable you to subscribe to a single webhook event to receive all notifications related to the event. For example, a subscription to the
customer.custom_attribute.visible.updated event includes notifications for the
customer.custom_attribute.owned.updated event because the custom attributes owned by your application are also visible to your application.
.public event types and replacement
.visible event types apply to a different set of events. Both are invoked for changes to any custom attributes or definitions whose
visibility is set to
VISIBILITY_READ_WRITE_VALUES. In addition,
.visible event types are invoked for changes to custom attributes or definitions that are owned by the subscribing application and set to
The deprecated non-public event types and replacement
.owned event types apply to the same set of events. Both are invoked for changes to custom attributes or definitions that are owned by the subscribing application. The names have been changed to clarify the scope.