Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Customer Custom Attributes

  • List customer custom attribute definitions

  • Create customer custom attribute definition

  • Delete customer custom attribute definition

  • Retrieve customer custom attribute definition

  • Update customer custom attribute definition

  • Bulk upsert customer custom attributes

  • List customer custom attributes

  • Delete customer custom attribute

  • Retrieve customer custom attribute

  • Upsert customer custom attribute

  • Webhooks

  • customer.custom_attribute_definition.owned.created

  • customer.custom_attribute_definition.owned.deleted

  • customer.custom_attribute_definition.owned.updated

  • customer.custom_attribute_definition.visible.created

  • customer.custom_attribute_definition.visible.deleted

  • customer.custom_attribute_definition.visible.updated

  • customer.custom_attribute.owned.deleted

  • customer.custom_attribute.owned.updated

  • customer.custom_attribute.visible.deleted

  • customer.custom_attribute.visible.updated

<- Customer Custom Attributes API

Customer Custom Attributes API

All versions ->

Update customer custom attribute definition

PUT

 /v2/customers/custom-attribute-definitions/{key}

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

Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type.

Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

Permissions:CUSTOMERS_WRITE

Guide

Update customer custom attribute definition

Try in API Explorer
Link to section

Path parameters

Example code

Link to section

key

string

Required

The key of the custom attribute definition to update.

Link to section

Request body

Link to section

custom_attribute_definition

Required

The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, so only new or changed fields need to be included in the request. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type. Only changes to the named options or the maximum number of allowed selections are supported.

For more information, see Updatable definition fields.

To enable optimistic concurrency control, include the optional version field and specify the current version of the custom attribute definition.

Link to section

idempotency_key

string

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

Max Length
45
Link to section

Response fields

Link to section

custom_attribute_definition

The updated custom attribute definition.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

PUT /v2/customers/custom-attribute-definitions/{key}
curl https://connect.squareup.com/v2/customers/custom-attribute-definitions/favoritebeverage \ -X PUT \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "custom_attribute_definition": { "schema": { "items": { "names": [ "water", "lemonade" ], "enum": [ "d012755e-6a3e-4fb8-8c17-d64f8483ecc9", "e21131a1-f1bc-467f-af95-4efb532bdd1a" ] } } } }'

Response JSON

{ "custom_attribute_definition": { "key": "favoritebeverage", "name": "Favorite Beverage", "description": "The favorite beverage of the customer.", "version": 2, "updated_at": "2022-04-26T16:08:48Z", "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "type": "array", "items": { "names": [ "water", "lemonade" ], "enum": [ "d012755e-6a3e-4fb8-8c17-d64f8483ecc9", "e21131a1-f1bc-467f-af95-4efb532bdd1a" ] }, "maxItems": 1, "uniqueItems": true }, "created_at": "2022-04-26T16:00:37Z", "visibility": "VISIBILITY_HIDDEN" } }