Create location custom attribute definitionBeta

POST

/v2/locations/custom-attribute-definitions

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

Use this endpoint to define a custom attribute that can be associated with locations. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. After the definition is created, you can call UpsertLocationCustomAttribute or BulkUpsertLocationCustomAttributes to set the custom attribute for locations.

Permissions:MERCHANT_PROFILE_WRITE

Guide

Create location custom attribute definition

Try in API Explorer

Link to section

Request body

Example code

Link to section

custom_attribute_definition

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 Supported data types.
name is required unless visibility is set to VISIBILITY_HIDDEN.

Link to section

idempotency_key

string

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

Max Length

Link to section

Response fields

Link to section

custom_attribute_definition

The new custom attribute definition.

Link to section

errors

Any errors that occurred during the request.

curl https://connect.squareup.com/v2/locations/custom-attribute-definitions \ -X POST \ -H 'Square-Version: 2025-04-16' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "custom_attribute_definition": { "key": "services-offered", "name": "Services offered", "description": "The services offered at this location", "visibility": "VISIBILITY_READ_ONLY", "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "names": [ "Wood repair", "Leather repair", "Reupholstery" ] } } } }'

{ "custom_attribute_definition": { "key": "services-offered", "name": "Services offered", "description": "The services offered at this location", "version": 1, "updated_at": "2022-12-06T15:57:23.211Z", "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "maxItems": 3, "type": "array", "uniqueItems": true, "items": { "names": [ "Wood repair", "Leather repair", "Reupholstery" ], "enum": [ "46efa55a-1f1d-467f-9733-468f881a4f20", "954998e1-b666-43a4-baf3-89cb87afe25a", "610fa590-70cd-4ec9-b64c-1dad6ba3c8f9" ] } }, "created_at": "2022-12-06T15:57:23.211Z", "visibility": "VISIBILITY_READ_ONLY" } }