• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Create customer custom attribute definition

POST /v2/customers/custom-attribute-definitions

Creates a customer-related custom attribute definition for a Square seller account.

Use this endpoint to define a custom attribute that can be associated with customer profiles.

A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. After the definition is created, you can call UpsertCustomerCustomAttribute or BulkUpsertCustomerCustomAttributes to set the custom attribute for customer profiles in the seller's Customer Directory.

Sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

Name Description
custom_attribute_definition
CustomAttributeDefinition

Required

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Specifying the schema.
  • If provided, name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.
  • All custom attributes are visible in exported customer data, including those set to VISIBILITY_HIDDEN.
idempotency_key
string

A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

Max Length 45

Response Fields

Name Description
custom_attribute_definition
CustomAttributeDefinition

The new custom attribute definition.

errors
Error [ ]

Any errors that occurred during the request.

Examples

Example:
You are viewing an old version of the API
POST /v2/customers/custom-attribute-definitions
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/customers/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "description": "The favorite beverage of the customer.",
      "key": "favoritebeverage",
      "name": "Favorite Beverage",
      "schema": {
        "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
        "type": "array",
        "items": {
          "names": [
            "water",
            "lemonade",
            "iced tea"
          ]
        },
        "maxItems": 1,
        "uniqueItems": true
      },
      "visibility": "VISIBILITY_HIDDEN"
    }
  }'
Response JSON
{
  "custom_attribute_definition": {
    "key": "favoritebeverage",
    "name": "Favorite Beverage",
    "description": "The favorite beverage of the customer.",
    "version": 1,
    "updated_at": "2022-04-26T16:00:37Z",
    "schema": {
      "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
      "type": "array",
      "items": {
        "names": [
          "water",
          "lemonade",
          "iced tea"
        ],
        "enum": [
          "d012755e-6a3e-4fb8-8c17-d64f8483ecc9",
          "e21131a1-f1bc-467f-af95-4efb532bdd1a",
          "1c980583-2c0c-483b-af48-d6598a05320f"
        ]
      },
      "maxItems": 1,
      "uniqueItems": true
    },
    "created_at": "2022-04-26T16:00:37Z",
    "visibility": "VISIBILITY_HIDDEN"
  }
}