Learn how to create and manage custom attributes for Square customer profiles using the Customer Custom Attributes API.
Customer Custom Attributes API

Create and Manage Customer Custom Attributes

Customer-related custom attributes are used to store properties or metadata for a customer profile. A custom attribute is based on a custom attribute definition in a Square seller account. After the definition is created, the custom attribute can be set for customer profiles in the seller's Customer Directory. For an overview of how customer-related custom attributes work, see Custom Attributes for Customers.

Customer-related custom attributes are stored as a collection for a customer profile.

.../v2/customers/{customer_id}/custom-attributes

An individual custom attribute is accessed using the customer_id and key. If the requesting application is not the definition owner, key is a qualified key

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

.../v2/customers/{customer_id}/custom-attributes/{key}

A custom attribute is represented by a CustomAttribute object. Custom attributes obtain a key identifier, visibility setting, allowed data type, and other properties from a custom attribute definition, which is represented by a CustomAttributeDefinition object.

The following is an example custom attribute:

The following fields represent core properties of a custom attribute:

Field
Description
keyThe identifier for the custom attribute, which is obtained from the custom attribute definition.

If the requesting application is not the definition owner, the key is a qualified key. For more information, see Qualified keys.
versionThe version number of the custom attribute. The version number is initially set to 1 and incremented each time the custom attribute value is updated. Include this field in upsert operations to enable optimistic concurrency control and in read operations for strong consistency.
visibilityThe level of access that other applications have to the custom attribute. Custom attributes obtain this setting from the visibility field of the current version of the definition.
definitionThe CustomAttributeDefinition object that defines properties for the custom attribute. This field is included if the custom attribute is retrieved using the with_definition or with_definitions query parameter set to true.
valueThe value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Value data types. The size of this field cannot exceed 5 KB.

When working with custom attributes owned by other applications, you must provide a qualified key for the following endpoints:

  • UpsertCustomerCustomAttribute

  • BulkUpsertCustomerCustomAttributes

  • RetrieveCustomerCustomAttribute

  • DeleteCustomerCustomAttribute

Square generates a qualified key in the format {application ID}:{key}, using the application ID of the definition owner and the key that was provided when the definition was created.

The following example is a qualified key generated for a third-party application:

sq0idp-BuahoY39o1X-GPxRRUWc0A:businessEmail

The following example is a qualified key for a seller-defined custom field created in the Customer Directory. The application ID for first-party Square products is square.

square:0460be56-6783-4482-8d55-634f9ae61684


You can call the following endpoints to get a qualified key:

Square returns qualified keys for custom attributes and custom attribute definitions when the requesting application is not the definition owner.

Note

In addition, the visibility setting of the custom attribute must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. For more information, see Access control.

Custom fields created in the Customer Directory are always set to VISIBILITY_READ_WRITE_VALUES.

The following data types are supported for customer-related custom attributes:

Data type Example value
String "Nellie"
"The quick brown fox."
Email "[email protected]"
PhoneNumber "+12085551234"
Address {
  "address_line_1": "Chez Mireille COPEAU Apartment 3",
  "address_line_2": "Entrée A Bâtiment Jonquille",
  "postal_code": "33380 MIOS",
  "locality": "CAUDOS",
  "country": "FR"
}
Date "2022-05-12"
Boolean true
false
Number "48"
"12.3"
Selection [
  "6b96fba7-d8a5-ae72-48f4-8c3ee875633f",
  "46c2716e-f559-4b75-c015-764897e3c4a0"
]

Note

For more information about these data types, including constraints and example requests for setting custom attribute values, see Upsert request examples for each data type.

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

The data type of a custom attribute is specified by the schema field of the custom attribute definition. You can call the following endpoints to retrieve a definition:

All data types except Selection are specified using a simple URL reference to an object hosted on the Square CDN. A Selection data type provides additional information.

The following is an example String-type custom attribute definition:

The following is an excerpt of an example Selection-type custom attribute definition:

Note the following:

  • The maxItems field represents the maximum number of allowed selections for the custom attribute value.

  • The items field contains two arrays: names and enum. 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.

This mapping is used to set the custom attribute value. For example, the value of the following custom attribute maps to Option 2.

For more example UpsertCustomerCustomAttribute requests, see Upsert request examples for each data type.

To set the value of a custom attribute for a customer profile, call UpsertCustomerCustomAttribute and provide the following information:

  • customer_id. The id of the Customer object that represents the target customer profile.

  • key. The key of the custom attribute to create or update.

    • If the requesting application is the definition owner, use the key that was provided when the definition was created.

    • If the requesting application is not the definition owner, use the qualified key

      The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
      . The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

  • custom_attribute. The custom attribute with the following fields:

    • value. The value of the custom attribute, which must conform to the schema specified by the definition and cannot exceed 5 KB. For more information, see Value data types.

    • version. The current version of the custom attribute, optionally included to enable optimistic concurrency control when updating a value that was previously set for the customer profile. If the specified version is less than the current version of the custom attribute, the request fails with a CONFLICT error. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

  • idempotency_key. A unique ID for the request that can be optionally included to ensure idempotency.

The following example request sets the value for a String-type custom attribute. The key in this example is favoritebook.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/favoritebook \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "Dune"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following is an example response:

During upsert operations, Square validates the provided value against the schema specified by the definition.

After a custom attribute is upserted, Square invokes the customer.custom_attribute.owned.updated and customer.custom_attribute.visible.updated webhook events.

Note

To view your custom attributes in the Customer Directory, the visibility setting must be VISIBILITY_READ_WRITE_VALUES and the seller must make the field visible from the Configure Profiles page. These custom attributes appear in the Personal Information tile of customer profiles that have been assigned a value. You must refresh the page to see an updated value.

You can set a corresponding custom attribute for a customer profile by providing a value that conforms to the schema specified by the custom attribute definition. For information about getting the schema, see Value data types.

The following sections contain UpsertCustomerCustomAttribute requests for each supported data type.

A string with up to 1000 UTF-8 characters. Empty strings are allowed.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "Medium drip coffee"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

An email address consisting of ASCII characters that matches the regular expression for the HTML5 email type.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "[email protected]"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

A string representation of a phone number in E.164 format. For example, +17895551234.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "+16095551234"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

An Address object. For information about Address fields, see Working with Addresses. You must provide a complete Address object in every upsert request.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": {
        "address_line_1": "1455 Market Street",
        "postal_code": "94103",
        "country": "US",
        "administrative_district_level_1": "California",
        "locality": "San Francisco"
      }
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

A date in ISO 8601 format: YYYY-MM-DD.

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

Note

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

A true or false value. A Toggle custom field created by sellers in the Customer Directory is a Boolean.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": true
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

A string representation of an integer or decimal with up to 5 digits of precision. Negative numbers are denoted using a - prefix. The absolute value cannot exceed (2^63-1)/10^5, or 92233720368547.

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "12.5"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

A selection from a set of named options.

When working with a Selection-type custom attribute, you need to get the schema from the custom attribute definition. The schema shows the mapping between the named options and Square-assigned UUIDs and the maximum number of allowed selections.

Reading the schema

The following is an excerpt of an example Selection-type custom attribute definition:

Note the following:

  • The maxItems field represents the maximum number of allowed selections for the custom attribute value.

  • The items field contains two arrays: names and enum. 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.


Setting a selection value

To set a selection value for a customer profile, you provide the target UUID (that maps to the target named option) in the value field. For this data type, value is an array that can contain zero or more UUIDs, up to the number specified in maxItems.

The following example request sets two selections for a custom attribute by providing two UUIDs:

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": [
        "9492bdda-ab4d-4eeb-8496-0986c8f78499",
        "4032c1a2-d749-4c75-9c30-be6472cd2e08"
      ]
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following example request sets an empty selection by providing an empty array:

Upsert Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": []
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

To create or update one or more custom attributes for one or more customer profiles, call BulkUpsertCustomerCustomAttributes. This endpoint accepts a values map with 1 to 25 objects that each contain:

  • An arbitrary ID for the individual upsert request, which corresponds to an entry in the response that has the same ID. The ID must be unique within the BulkUpsertCustomerCustomAttributes request.

  • An individual upsert request with the information needed to create or update a custom attribute for a customer profile.

The following example includes two upsert requests that set two custom attributes for two customer profiles:

During upsert operations, Square validates each provided value against the schema specified by the definition. The optional version field is only supported for update operations.

Did you know?

If you are providing idempotency keys, you can use them as the arbitrary ID for individual upsert requests.

An individual upsert request contains the information needed to set the value of a custom attribute for a customer profile. Each request includes the following fields:

  • customer_id. The id of the Customer object that represents the target customer profile.

  • custom_attribute. The custom attribute with following fields:

    • key. The key of the custom attribute to create or update.

      • If the requesting application is the definition owner, use the key that was provided when the definition was created.

      • If the requesting application is not the definition owner, use the qualified key

        The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
        . The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

    • value. The value of the custom attribute, which must conform to the schema specified by the definition and cannot exceed 5 KB. For more information, see Value data types.

    • version. The current version of the custom attribute, optionally included to enable optimistic concurrency control when updating a value that was previously set for the customer profile. If the specified version is less than the current version of the custom attribute, the request fails with a CONFLICT error. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

  • idempotency_key. A unique ID for the individual request that can be optionally included to ensure idempotency.

The following example BulkUpsertCustomerCustomAttributes request includes five individual upsert requests:

Bulk Upsert Customer Custom Attributes
  • 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
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
curl https://connect.squareupsandbox.com/v2/customers/custom-attributes/bulk-upsert \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "values": {
      "id1": {
        "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
        "custom_attribute": {
          "key": "favoritebook",
          "value": "Dune"
        },
        "idempotency_key": "{UNIQUE_KEY}"
      },
      "id2": {
        "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
        "custom_attribute": {
          "key": "favoritebook",
          "value": "Through the Looking Glass",
          "version": 2
        },
        "idempotency_key": "{UNIQUE_KEY}"
      },
      "id3": {
        "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
        "custom_attribute": {
          "key": "favoritemovie",
          "value": "Apocalypse Now",
          "version": 3
        },
        "idempotency_key": "{UNIQUE_KEY}"
      },
      "id4": {
        "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
        "custom_attribute": {
          "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
          "value": "10.5"
        },
        "idempotency_key": "{UNIQUE_KEY}"
      },
      "id5": {
        "customer_id": "70548QG1HN43B05G0KCZ4MMC1G",
        "custom_attribute": {
          "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail",
          "value": "[email protected]",
          "version": 1
        },
        "idempotency_key": "{UNIQUE_KEY}"
      }
    }
  }'

The following is an example response. Note that the errors field is returned for any individual requests that fail.

  • 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
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
{
  "values": {
    "id2": {
      "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
      "custom_attribute": {
        "key": "favoritebook",
        "version": 3,
        "updated_at": "2022-05-30T00:16:23Z",
        "value": "Through the Looking Glass",
        "created_at": "2022-05-20T20:20:35Z",
        "visibility": "VISIBILITY_READ_WRITE_VALUES"
      }
    },
    "id1": {
      "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
      "custom_attribute": {
        "key": "favoritebook",
        "version": 1,
        "updated_at": "2022-05-30T00:16:23Z",
        "value": "Dune",
        "created_at": "2022-05-30T00:16:23Z",
        "visibility": "VISIBILITY_READ_WRITE_VALUES"
      }
    },
    "id3": {
      "errors": [
        {
          "code": "CONFLICT",
          "detail": "Attempting to write to version 3, but current version is 4",
          "field": "version",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    },
    "id4": {
      "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
      "custom_attribute": {
        "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
        "version": 1,
        "updated_at": "2022-05-30T00:16:23Z",
        "value": "10.5",
        "created_at": "2021-11-08T23:14:47Z",
        "visibility": "VISIBILITY_READ_WRITE_VALUES"
      }
    },
    "id5": {
      "customer_id": "70548QG1HN43B05G0KCZ4MMC1G",
      "custom_attribute": {
        "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail",
        "version": 2,
        "updated_at": "2022-05-30T00:16:23Z",
        "value": "[email protected]",
        "created_at": "2022-05-29T03:51:18Z",
        "visibility": "VISIBILITY_READ_WRITE_VALUES"
      }
    }
  }
}

Individual upsert requests are not guaranteed to be returned in the same order. Each upsert response has the same ID as the corresponding upsert request, so you can use the ID to map individual requests and responses.

After each custom attribute is upserted, Square invokes the customer.custom_attribute.owned.updated and customer.custom_attribute.visible.updated webhook events.

To list the custom attributes that are set for a customer profile, call ListCustomerCustomAttributes and provide the following information:

  • customer_id. The id of the Customer object that represents the target customer profile.

  • with_definitions. Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

  • limit. The maximum page size of 1 to 100 results to return in the response. The default value is 20.

    If the results are paged, the cursor field in the response contains a value that you can send with the cursor query parameter to get the next page of results.

The following example request includes the limit query parameter:

List Customer Custom Attributes
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes?limit=4 \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

When all pages are retrieved, the results include:

  • All custom attributes owned by the requesting application that have a value. The key for these custom attributes is the key that was provided for the definition.

  • All custom attributes owned by other applications that have a value and a visibility setting of VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. The key for these custom attributes is a qualified key

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
    . For more information, see Qualified keys.

    A custom attribute is owned by the application that created the corresponding definition.

The following is an example response:

  • 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
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
{
  "custom_attributes": [
    {
      "key": "entity-id",
      "version": 1,
      "updated_at": "2022-05-30T09:44:42Z",
      "value": "mbj_004508",
      "created_at": "2022-05-30T09:44:42Z",
      "visibility": "VISIBILITY_HIDDEN"
    },
    {
      "key": "favoritebook",
      "version": 3,
      "updated_at": "2022-05-30T00:16:23Z",
      "value": "Through the Looking Glass",
      "created_at": "2022-05-20T20:20:35Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    {
      "key": "sq0idp-BuahoY39o1X-GPxRRUWc0A:businessAddress",
      "version": 2,
      "updated_at": "2022-05-31T17:40:28Z",
      "value": {
        "address_line_1": "1455 Market Street",
        "postal_code": "94103",
        "country": "US",
        "administrative_district_level_1": "California",
        "locality": "San Francisco"
      },
      "created_at": "2022-05-26T17:08:57Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    {
      "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
      "version": 4,
      "updated_at": "2022-05-16T00:16:23Z",
      "value": "10.5",
      "created_at": "2021-11-08T23:14:47Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  ],
  "cursor": "O5tF0DmcskdGTrPOAPjlIL...BxACXlOQYbdKq0RC4LZ"
}

The following example request includes the with_definitions query parameter set to true:

List Customer Custom Attributes
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes?with_definitions=true \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an excerpt of an example response that shows the custom attribute definition in the definition field:

If no custom attributes are found, Square returns an empty object.

To retrieve a custom attribute from a customer profile, call RetrieveCustomerCustomAttribute and provide the following information:

  • customer_id. The id of the Customer object that represents the target customer profile.

  • key. The key of the custom attribute to retrieve.

    • If the requesting application is the definition owner, use the key that was provided when the definition was created.

    • If the requesting application is not the definition owner, use the qualified key

      The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
      . The visibility of the custom attribute must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

  • with_definition. Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

  • version. The current version of the custom attribute, optionally included 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 a 400 BAD_REQUEST error.

The following is an example request:

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

The following is an example response for an Address-type custom attribute. The value field contains the value of the custom attribute.

The following example request includes the with_definition query parameter:

Retrieve Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key}?with_definition=true \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following example response shows the custom attribute definition in the definition field. This example defines a Selection-type custom attribute. The mapping information in the schema.items field is used to determine the custom attribute value.

The names field contains the named options and the enum field contains the corresponding Square-assigned UUIDs. The named options map by index to the UUIDs. The first option maps to the first UUID, the second option maps to the second UUID, and so on. Therefore, the UUID in the value field of this custom attribute maps to the Small option.

  • 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
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
{
  "custom_attribute": {
    "key": "shirt-size",
    "version": 1,
    "definition": {
      "key": "shirt-size",
      "name": "Default shirt size",
      "description": "The default shirt size ordered by the customer.",
      "version": 1,
      "updated_at": "2022-05-20T00:27:17Z",
      "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": [
            "1a052285-7224-4d25-9232-69f941bb0612",
            "4034d1bb-ff6c-4f7f-9108-a01625e8aadd",
            "fb27f80b-24e1-463b-9aa1-d32fcec6b22a"
          ]
        }
      },
      "created_at": "2022-05-20T00:27:17Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    "updated_at": "2022-05-26T16:19:07Z",
    "value": [
      "1a052285-7224-4d25-9232-69f941bb0612"
    ],
    "created_at": "2022-05-26T16:19:07Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

If the custom attribute is not set for the specified customer profile, Square returns the following response:

If the custom attribute is not available for customer profiles in the directory, Square returns the following response:

To delete a custom attribute from a customer profile, call DeleteCustomerCustomAttribute and provide the following information:

  • customer_id. The id of the Customer object that represents the target customer profile.

  • key. The key of the custom attribute to delete.

    • If the requesting application is the definition owner, use the key that was provided when the definition was created.

    • If the requesting application is not the definition owner, use the qualified key

      The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
      . The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

The following is an example request:

Delete Customer Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/custom-attributes/{key} \
  -X DELETE \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If the operation is successful, Square returns an empty object:

After a custom attribute is deleted, Square invokes the customer.custom_attribute.owned.deleted and customer.custom_attribute.visible.deleted webhook events.

We've made improvements to our docs.
Prefer the old format?