Applies to: Location Custom Attributes API
Learn how to define location-related custom attributes for Square sellers using the Location Custom Attributes API.
A custom attribute definition specifies the key
identifier, the visibility
setting, the schema
data type, and other properties for a custom attribute. After the definition is created, an associated custom attribute can be created and assigned to sellers' locations. For more information about how location-related custom attributes work, see Custom Attributes for Locations.
A custom attribute definition is represented by a CustomAttributeDefinition
object. The following is an example custom attribute definition that defines a "repairs" custom attribute of the Boolean
data type:
{
"custom_attribute_definition": {
"key": "repairs",
"name": "Accepts repairs",
"description": "Does this location handle repairs?",
"version": 1,
"updated_at": "2023-01-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
The following fields represent core properties of a custom attribute definition:
Field | Description |
---|---|
key | The identifier for the definition and its corresponding custom attributes. This key value is unique for the application and cannot be changed after the definition is created.The field can contain up to 60 alphanumeric characters, periods ( . ), underscores (_ ), and hyphens (- ) and must match the following regular expression: ^[a-zA-Z0-9\._-]{1,60}$ . |
name | The name for the custom attribute. This field is required unless the visibility field is set to VISIBILITY_HIDDEN . |
description | The description for the custom attribute. This field is required unless the visibility field is set to VISIBILITY_HIDDEN . |
visibility | The access control setting that determines whether other applications (including Square products such as the Square Dashboard) can view the definition and view or edit corresponding custom attributes. Valid values are VISIBILITY_HIDDEN , VISIBILITY_READ_ONLY , and VISIBILITY_READ_WRITE_VALUES . |
schema | The data type of the custom attribute value. For more information, see Supported data types. The total schema size cannot exceed 12 KB. |
version | The version number of the custom attribute definition. The version number is initially set to 1 and incremented each time the definition is updated. Include this field in update operations to enable optimistic concurrency control and in read operations for strong consistency. |
Use the CreateLocationCustomAttributeDefinition endpoint to create a custom attribute definition for a seller account. This operation makes the custom attribute available to the seller and their locations.
The following request creates a custom attribute definition to represent the name of a location's general manager. The schema
field indicates that the value of the custom attribute is a String
.
Create location custom attribute definition
The following is an example response:
{
"custom_attribute_definition": {
"key": "general-manager",
"name": "General Manager",
"description": "The General Manager at this Location",
"version": 1,
"updated_at": "2023-01-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
Now that the custom attribute definition is created, you can set the custom attribute for the seller's locations individually or in bulk.
After a custom attribute definition is created, Square invokes the location.custom_attribute_definition.owned.created
and location.custom_attribute_definition.visible.created
webhooks.
A seller account can have a maximum of 100 location-related custom attribute definitions per application.
For a Selection
data type, the schema contains a $schema
field that references a JSON meta-schema object, as well as additional fields. Note the following:
$schema
references thehttps://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json meta-schema
hosted on the Square CDN.type
must bearray
.items
must include anames
array that contains strings representing the display names of the predefined options that can be selected. Note that the order of the options might not be respected by all UIs.maxItems
is an integer that represents the maximum number of allowed selections. Corresponding custom attributes can have zero or more selected values, up to the specified maximum. The minimum value is 1 and cannot exceed the number of options in thenames
field.uniqueItems
must betrue
.
The following example request creates a Selection
-type custom attribute definition that contains three named options and allows for a selection of all three:
Create location custom attribute definition
The following is an example response. For each named option, Square generates a UUID and adds it to the enum
field. 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.
These UUIDs are used to set the value of the custom attribute or update the option names.
{
"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.0,
"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"
}
}
Use the UpdateLocationCustomAttributeDefinition endpoint to update a custom attribute definition for a seller account. The 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 aSelection
data type
Note the following about an UpdateLocationCustomAttributeDefinition
request:
- A custom attribute definition can only be updated by the definition owner.
- The
key
path parameter is thekey
of the custom attribute definition. - The
version
field must match the current version of the custom attribute definition to enable optimistic concurrency control. If this isn't important for your application,version
can be set to -1. For any other values, the request fails with aBAD_REQUEST
error. Square increments the version number each time the definition is updated. - The
idempotency_key
is a unique ID for the request that can be optionally included to ensure idempotency. - Changes to the
visibility
setting are propagated to corresponding custom attributes within a few seconds. At that time, theupdated_at
andversion
fields of the custom attributes are also updated. ForVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
settings, the definition must have both aname
and adescription
.
The following request updates the visibility
setting of a definition:
Update location custom attribute definition
The following is an example response:
{
"custom_attribute_definition": {
"key": "general-manager",
"name": "General Manager",
"description": "The General Manager at this Location",
"version": 2,
"updated_at": "2023-02-02T04:17:09Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
After a location-related custom attribute definition is updated, Square invokes the location.custom_attribute_definition.owned.updated
and location.custom_attribute_definition.visible.updated
webhooks.
Did you know?
To simplify management, you might want to keep all definitions that use the same key synchronized across seller accounts. Therefore, if you change a definition for one seller, you should consider making the same change for all other sellers.
For a Selection
data type, you can update the maximum number of allowed selections and the set of predefined named options.
Note
Square validates custom attribute selections on upsert operations, so these changes apply only for future upsert operations. They don't affect custom attributes that have already been set on a location.
The information you send in the UpdateLocationCustomAttributeDefinition request depends on the change you want to make:
- To change the maximum number of allowed selections, include the
maxItems
field with the new integer value. The minimum value is 1 and cannot exceed the number of options in thenames
field. - To change the set of predefined named options, include the
items
field with the completenames
andenum
arrays. The options in thenames
array map by index to the Square-assigned UUIDs in theenum
array, which are unique per seller. The first option maps to the first UUID, the second option maps to the second UUID, and so on.- To add an option:
- Add the name of the new option at the end of the
names
array. New options must always be added to the end of the array. - Don't change the
enum
array. Square generates a UUID for the new option and adds it to the end of the enum array.
- Add the name of the new option at the end of the
- To reorder the options:
Change the order of the names in the
names
array.Change the order of the UUIDs in the
enum
array so that the order of the UUIDs matches the order of the corresponding named options.Note that the order might not be respected by all UIs.
- To remove an option:
- Remove the name of the option from the
names
array. - Remove the corresponding UUID from the
enum
array.
- Remove the name of the option from the
- To add an option:
The following UpdateLocationCustomAttributeDefinition
request adds two new options by adding their names at the end of the names
array:
Update location custom attribute definition
The following example response includes the UUIDs that Square generated for the new Furniture consignment
and Rug cleaning
options:
{
"custom_attribute_definition": {
"key": "services-offered",
"name": "Services offered",
"description": "The services offered at this location",
"version": 2,
"updated_at": "2023-01-09T15:57:23.211Z",
"schema": {
"$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
"maxItems": 3.0,
"type": "array",
"uniqueItems": true,
"items": {
"names": [
"Wood repair",
"Leather repair",
"Reupholstery",
"Furniture consignment",
"Rug cleaning"
],
"enum": [
"46efa55a-1f1d-467f-9733-468f881a4f20",
"954998e1-b666-43a4-baf3-89cb87afe25a",
"610fa590-70cd-4ec9-b64c-1dad6ba3c8f9",
"gEtd3Mvh-49yt-7yUz-rXDt-vL4XzYgRcmq4",
"pbGg9Zmb-e5kw-9zmb-75CQ-yTg8mJW8j2oc"
]
}
},
"created_at": "2022-12-06T15:57:23.211Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
Use the ListLocationCustomAttributeDefinitions endpoint to list the custom attribute definitions from a seller account.
The limit query parameter optionally specifies a maximum page size of 100 results. The default limit is 20 results. If the results are paged, the cursor
field in the response contains a value that you can send with the cursor
query parameter to retrieve the next page of results.
The following example request includes the limit query parameter:
List location custom attribute definitions
When all pages are retrieved, all custom attribute definitions created by the requesting application are included in the results. The key
for these definitions is the key
value that was provided when the definition was created.
Custom attribute definitions created by other applications are included if their visibility
setting is VISIBILITY_READ_ONLY
or VISIBILITY_READ_WRITE_VALUES
.
The following is an example response containing four custom attribute definitions:
{
"custom_attribute_definitions": [
{
"key": "general-manager",
"name": "General Manager",
"description": "The General Manager at this Location",
"version": 2,
"updated_at": "2023-02-02T04:17:09Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_ONLY"
},
{
"key": "manager-email",
"name": "Manager Email",
"description": "The email address of the general manager",
"version": 1,
"updated_at": "2023-01-20T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Email"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_HIDDEN"
},
{
"key": "minimum",
"name": "Min staffing requirements",
"description": "The minimum number of staff required for the location to function",
"version": 1,
"updated_at": "2022-12-02T19:51:29.235Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
},
"created_at": "2022-12-02T19:51:29.235Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"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.0,
"type": "array",
"uniqueItems": true,
"items": {
"names": [
"Wood repair",
"Leather repair",
"Reupholstery",
"Furniture consignment",
"Rug cleaning"
],
"enum": [
"46efa55a-1f1d-467f-9733-468f881a4f20",
"954998e1-b666-43a4-baf3-89cb87afe25a",
"610fa590-70cd-4ec9-b64c-1dad6ba3c8f9",
"gEtd3Mvh-49yt-7yUz-rXDt-vL4XzYgRcmq4",
"pbGg9Zmb-e5kw-9zmb-75CQ-yTg8mJW8j2oc"
]
}
},
"created_at": "2022-12-06T15:57:23.211Z",
"visibility": "VISIBILITY_READ_ONLY"
}
]
}
Note that the "General manager"
and "Manager email"
custom attribute definitions were created by the requesting application. Because "Manager email"
is set to VISIBILITY_HIDDEN
, it's returned only when requested by the definition owner.
If no custom attribute definitions are found, Square returns an empty response.
{}
Use the RetrieveLocationCustomAttributeDefinition endpoint to retrieve a custom attribute definition using its key
. Note the following:
- The
key
path parameter is thekey
value of the custom attribute definition. - The
version
query parameter is optionally 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 later version if one exists. If the specified version is later than the current version, Square returns a400 BAD_REQUEST
error.
The following is an example request:
Retrieve location custom attribute definition
Note
Square also returns custom attribute definitions for RetrieveLocationCustomAttribute
or ListLocationCustomAttributes
requests if you set the with_definition
or with_definitions
query parameter to true
. For more information, see Retrieve a location custom attribute or List location custom attributes.
The following is an example response:
{
"custom_attribute_definition": {
"key": "general-manager",
"name": "General Manager",
"description": "The General Manager at this Location",
"version": 2,
"updated_at": "2023-02-02T04:17:09Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
If the custom attribute definition isn't found, Square returns an errors
field that contains a 404 NOT_FOUND
error.
Use the DeleteLocationCustomAttributeDefinition endpoint to delete a custom attribute definition from a seller account. Note the following:
- Only the definition owner can delete a custom attribute definition.
- The
key
path parameter is thekey
value of the custom attribute definition. - Deleting a custom attribute definition also deletes the corresponding custom attribute from all locations on which it has been set.
The following is an example request:
Delete location custom attribute definition
If successful, Square returns an empty object.
{}
After a custom attribute definition is deleted, Square invokes the location.custom_attribute_definition.owned.deleted
and location.custom_attribute_definition.visible.deleted
webhooks.