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

Retrieve customer custom attribute definition

GET

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

Retrieves a customer-related custom attribute definition from a Square seller account.

To retrieve a custom attribute definition created by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

Permissions:CUSTOMERS_READ

Guide

Retrieve 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 retrieve. If the requesting application is not the definition owner, you must use the qualified key.

Link to section

Query parameters

Link to section

version

integer(32-bit)

The current version of the custom attribute definition, which is used 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 BAD_REQUEST error.

Link to section

Response fields

Link to section

custom_attribute_definition

The retrieved custom attribute definition.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

GET /v2/customers/custom-attribute-definitions/{key}
curl https://connect.squareup.com/v2/customers/custom-attribute-definitions/favoritemovie \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json'

Response JSON

{ "custom_attribute_definition": { "key": "favoritemovie", "name": "Favorite Movie", "description": "The favorite movie of the customer.", "version": 1, "updated_at": "2022-04-26T15:27:30Z", "schema": { "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String" }, "created_at": "2022-04-26T15:27:30Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } }