Learn how custom attributes can be added to Square customer profiles using the Customer Custom Attributes API.
Customer Custom Attributes API

Custom Attributes for Customer Profiles Beta release
This is pre-release documentation for an API in public beta and is subject to change.

Custom attributes store properties or metadata that can be used to simplify integration and synchronization or enable new personalization workflows. You can define custom attributes that can be associated with customer profiles, such as Favorite Drink, Occupation, Last Check-In Date, and Entity ID.

A custom attribute obtains a key identifier, visibility setting, allowed data type, and other properties from a custom attribute definition. This relationship is shown in the following diagram:

A diagram showing how properties of a custom attribute definition are used by corresponding custom attributes.

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.

Basic workflow Permalink Get a link to this section

For a high-level understanding of how you can use the Customer Custom Attributes API to work with customer-related custom attributes, it is helpful to focus on three basic operations:

  1. Creating a custom attribute definition for a seller

  2. Setting custom attributes for customer profiles

  3. Retrieving custom attributes from customer profiles

Creating a custom attribute definition for a seller Permalink Get a link to this section

When you want to create a new customer-related custom attribute, you must first define its properties by calling CreateCustomerCustomAttributeDefinition.

The following example request defines a Favorite Drink custom attribute. The schema field indicates that the value of the custom attribute is a String.

Create Customer Custom Attribute Definition
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/customers/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "key": "favorite-drink",
      "visibility": "VISIBILITY_READ_WRITE_VALUES",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
      },
      "name": "Favorite Drink",
      "description": "The favorite drink of the customer"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The 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 first-party Square products) have to the definition and corresponding custom attributes.

Setting custom attributes for customer profiles Permalink Get a link to this section

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 customer_id and key. Note the following:

  • The key in the path is favorite-drink, which is the key specified by the definition.

  • The value in the request body sets the custom attribute value for the customer profile. This value must conform to the String data type specified by the schema field in the definition.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/favorite-drink \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "Double-shot breve"
    }
  }'

Note

Square also provides the BulkUpsertCustomerCustomAttribute endpoint to update multiple custom attributes and customer profiles in a single request.

Retrieving custom attributes from customer profiles Permalink Get a link to this section

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 customer_id and key:

Retrieve Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/favorite-drink \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The 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.

Note

Square also provides the ListCustomerCustomAttributes endpoint to retrieve all the custom attributes associated with a customer profile.

Supported operations Permalink Get a link to this section

The Customer Custom Attributes API supports the following operations:

Working with customer-related custom attribute definitions Permalink Get a link to this section

Working with customer-related custom attributes Permalink Get a link to this section

Note

Working with custom attributes is different than working with native attributes on the Customer object (such as given_name and email_address) that are accessed using the Customers API. For example, custom attributes are not returned in a RetrieveCustomer or ListCustomers response or managed using CreateCustomer or UpdateCustomer.

Supported data types Permalink Get a link to this section

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:

  • String

  • Email

  • PhoneNumber

  • Address

  • Date

  • Boolean

  • Number

  • Selection

Note

Customer-related custom attributes do not support DateTime or Duration data types.

For information about defining the data type for a customer-related custom attribute, see Specifying the schema.

Seller scope Permalink Get a link to this section

A 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:

A diagram showing two sellers using the same custom attribute.

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.

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 a definition for one seller, you should consider making the same change for all other sellers.

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 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 first-party Square products, such as the Customer Directory.

The following table shows the access permitted by each supported visibility setting.

Custom attribute definition Custom attribute
Visibility setting READ WRITE READ WRITE
VISIBILITY_HIDDEN (default) No No No1 No
VISIBILITY_READ_ONLY Yes No Yes2 No
VISIBILITY_READ_WRITE_VALUES Yes No Yes Yes

1. 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.

2. Customer-related custom attributes set to VISIBILITY_READ_ONLY are not currently visible in the Customer Directory or Point of Sale application.

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

To access custom attributes or definitions owned by other applications, the following conditions must be true:

  • The visibility field 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 the qualified key

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
    for the following requests:

    • RetrieveCustomerCustomAttributeDefinition

    • UpsertCustomerCustomAttribute

    • BulkUpsertCustomerCustomAttributes

    • RetrieveCustomerCustomAttribute

    • DeleteCustomerCustomAttribute


    To obtain a qualified key, call ListCustomerCustomAttributeDefinitions or 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.

Note

You should be aware of the following considerations when using custom attributes that are owned by other applications:

  • If the visibility of a custom attribute definition is updated, the change propagates to all corresponding custom attributes within a couple seconds.

  • If a custom attribute definition is deleted, all corresponding custom attributes are also deleted from customer profiles.

Webhooks Permalink Get a link to this section

You can subscribe to receive notifications for customer-related custom attribute events. Each event provides two options that allow you to receive notifications for the following changes:

  • Changes to custom attribute definitions and custom attributes owned by the subscribing application. This option applies to all custom attribute definitions and custom attributes owned by your application regardless of the visibility setting. This option also applies when other applications make changes to custom attributes that are owned by your application.

  • Changes to custom attribute definitions and custom attributes that are publicly visible. This option applies to all custom attribute definitions and custom attributes whose visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES, including those owned by your application.

Event notifications for both options contain the same information.

Webhook events Permalink Get a link to this section

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by the subscribing application:

Event
Description
customer.custom_attribute_definition.createdA custom attribute definition was created by your application.
customer.custom_attribute_definition.updatedA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
customer.custom_attribute_definition.deletedA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
customer.custom_attribute.updatedA custom attribute owned by your application was created or updated for a customer profile. A custom attribute is owned by the application that created the corresponding definition.
customer.custom_attribute.deletedA custom attribute owned by your application was deleted from a customer profile. A custom attribute is owned by the application that created the corresponding definition.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are publicly visible:

Event
Description
customer.custom_attribute_definition.public.createdA publicly visible custom attribute definition was created.
customer.custom_attribute_definition.public.updatedA publicly visible custom attribute definition was updated.
customer.custom_attribute_definition.public.deletedA publicly visible custom attribute definition was deleted.
customer.custom_attribute.public.updatedA publicly visible custom attribute was created or updated for a customer profile.
customer.custom_attribute.public.deletedA publicly visible custom attribute was deleted from a customer profile.

Note

Upserting or deleting a custom attribute for a customer profile does not invoke a customer.updated webhook.

The following is an example customer.custom_attribute_definition.created notification:

The following is an example customer.custom_attribute.updated notification:

Note the following:

  • Customer-related custom attribute events are available for webhook subscriptions starting in Square version 2022-05-12.

  • The CUSTOMERS_READ permission is required to receive notifications about customer-related custom attribute events.

  • The key of the custom attribute definition or custom attribute in the notification is always the qualified key

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
    .

  • If you subscribe to the non-public and public options for the same event, Square sends duplicate notifications for changes to custom attribute definitions and custom attributes whose visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

  • The value of the data.id in the notification depends on the affected object:

    • For custom attribute definition events, data.id is the qualified key.

    • For custom attribute events, data.id is generated using the qualified key and the ID of the affected customer profile. This data.id cannot be used directly with the Customer Custom Attributes API.

For more information about custom attribute webhooks, see Subscribing to webhooks. For more information about how to subscribe to events and validate notifications, see Square Webhooks Overview.

Requirements and limitations Permalink Get a link to this section

The following requirements, limitations, and other considerations apply when working with customer-related custom attributes:

  • Minimum Square version. Square version 2022-05-12 or 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. Do not 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 schema for a supported data type. The following data types are not supported for customer-related custom attributes:

    • DateTime

    • Duration

  • No search support. Searching customers by custom attribute is not currently supported.

  • Limits. A seller account can have a maximum of 100 customer-related custom attribute definitions per application.

  • Unique name. If the visibility of a customer-related custom attribute definition is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES, the name must 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 first-party Square products.

  • OAuth permissions. Applications that use OAuth require CUSTOMER_READ or CUSTOMER_WRITE permission to work with customer-related custom attributes. For more information, see OAuth API Overview and OAuth Permissions Reference.

    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 visibility setting.

Related topics Permalink Get a link to this section

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