Applies to: Location Custom Attributes API
Learn how to create and manage custom attribute values for Location objects.
Location-related custom attributes are used to store additional properties or metadata on Location
objects. A custom attribute is based on a custom attribute definition in a Square seller account. After the definition is created, the custom attribute can be set on a seller's locations. For an overview about how location-related custom attributes work, see Custom Attributes for Locations.
An individual custom attribute is accessed using the location_id
and key
.
.../v2/locations/{location_id}/custom-attributes/{key}
A custom attribute is represented by a CustomAttribute object. Custom attributes obtain a key
identifier, the visibility
setting, allowed data types, and other properties from a custom attribute definition, which is represented by a CustomAttributeDefinition object.
The following is an example custom attribute:
{
"custom_attribute": {
"key": "general-manager",
"version": 1,
"updated_at": "2023-01-10T21:13:48Z",
"value": "Christine Lee",
"created_at": "2023-01-10T21:13:48Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
The following table shows the core properties of a custom attribute:
Field | Description |
---|---|
key | The identifier for the custom attribute, which is obtained from the custom attribute definition. |
version | The version number of the custom attribute. The version number is initially set to 1 and incremented each time the custom attribute value is updated. Include this field in upsert operations to enable optimistic concurrency control and in read operations for strong consistency. |
value | The value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Supported data types. The size of this field cannot exceed 5 KB. |
visibility | The level of access that other applications have to the custom attribute. Custom attributes obtain this setting from the visibility field of the current version of the definition. |
definition | The CustomAttributeDefinition object that defines properties for the custom attribute. This field is included if the custom attribute is retrieved using the with_definition or with_definitions query parameter set to true . |
To set the value of a custom attribute for a location, call UpsertLocationCustomAttribute and provide the following information:
location_id
- The ID of theLocation
object that represents the target location.custom_attribute
- The custom attribute with the following fields:key
- The key of the custom attribute to create or update.- If the requesting application isn't the definition owner, the
visibility
field value of the custom attribute must beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. value
- The value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Supported data types.version
- The current version of the custom attribute, included to enable optimistic concurrency when updating a value that was previously set for the location. 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.
idempotency_key
- A unique ID for the request that can be optionally included to ensure idempotency.
The following example request sets the value for a String
-type custom attribute. The key
value in this example is general-manager
.
Upsert location custom attribute
The following is an example response:
{
"custom_attribute": {
"key": "general-manager",
"version": 1,
"updated_at": "2023-01-10T21:13:48Z",
"value": "Christine Lee",
"created_at": "2023-01-10T21:13:48Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
During upsert operations, Square validates the provided value against the schema specified by the definition.
After a custom attribute is upserted, Square invokes the location.custom_attribute.owned.updated
and location.custom_attribute.visible.updated
webhooks.
You can set a corresponding custom attribute for a location by providing a value that conforms to the schema specified by the custom attribute definition. The size of this field cannot exceed 5 KB.
The following sections contain UpsertLocationCustomAttribute
requests for each supported data type.
A string with up to 1000 UTF-8 characters. Empty strings are allowed.
Upsert location custom attribute
An email address consisting of ASCII characters that matches the regular expression for the HTML5 email
type.
Upsert location custom attribute
A string representation of a phone number in E.164 format. For example, +17895551234
.
Upsert location custom attribute
An Address object. For information about Address
fields, see Working with Addresses. You must provide a complete Address
object in every upsert request.
Upsert location custom attribute
A date in ISO 8601 format: YYYY-MM-DD
.
Upsert location custom attribute
A string representation of the date and time in the ISO 8601 format, starting with the year, followed by the month, day, hour, minutes, seconds, and milliseconds. For example, 2022-07-10 15:00:00.000
.
Upsert location custom attribute
A duration as defined by the ISO 8601 ABNF. For example, "P3Y6M4DT12H30M5S".
Upsert location custom attribute
A true
or false
value.
Upsert location custom attribute
A string representation of an integer or decimal with up to five digits of precision. Negative numbers are denoted using a - prefix.
Upsert location custom attribute
A selection from a set of named options.
When working with a Selection
-type custom attribute, you need to get the schema from the custom attribute definition. The schema shows the mapping between the named options and Square-assigned UUIDs and the maximum number of allowed selections.
Reading the schema
The following is an excerpt of an example Selection
-type custom attribute definition:
{ "custom_attribute_definition": { ... "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "maxItems": 3, "type": "array", "uniqueItems": true, "items": { "names": [ "Option 1", "Option 2", "Option 3" ], "enum": [ "9492bdda-ab4d-4eeb-8496-0986c8f78499", // UUID for "Option 1" "6b96fba7-d8a5-ae72-48f4-8c3ee875633f", // UUID for "Option 2" "4032c1a2-d749-4c75-9c30-be6472cd2e08" // UUID for "Option 3" ] } }, ... } }
- The
maxItems
field represents the maximum number of allowed selections for the custom attribute value. - The
items
field contains two arrays:names
andenum
. The options in thenames
field map by index to the UUIDs in theenum
field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.
Setting a Selection value
To set a Selection
value for a location, provide the target UUID (that maps to the target named option) in the value
field. For this data type, value
is an array that can contain zero or more UUIDs, up to the number specified in maxItems
.
The following request sets two selections for a custom attribute by providing two UUIDs:
Upsert location custom attribute
The following request sets an empty selection by providing an empty array:
Upsert location custom attribute
If necessary, you can update the maximum number of allowed selections and the set of predefined named options in the custom attribute definition.To learn more, see Updating a Selection schema.
To create or update one or more custom attributes for one or more locations, call BulkUpsertLocationCustomAttributes. This endpoint accepts a values
map with 1 to 25 objects that each contain:
- An arbitrary ID for the individual upsert request, which corresponds to an entry in the response that has the same ID. The ID must be unique within the
BulkUpsertLocationCustomAttributes
request. - An individual upsert request with the information needed to create or update a custom attribute for a location.
During upsert operations, Square validates each provided value against the schema specified by the definition. The version
field is only supported for update operations.
The following BulkUpsertLocationCustomAttributes
request includes four upsert requests that set four custom attributes on different locations:
Bulk upsert location custom attributes
The following is an example response. Note that:
- Individual upsert requests aren't guaranteed to be returned in the same order. Each upsert response has the same ID as the corresponding upsert request, so you can use the ID to map individual requests and responses.
- The
errors
field is returned for any individual requests that fail.
{
"values": {
"id2": {
"location_id": "7WQ0KXC8ZSD90",
"custom_attribute": {
"key": "repairs",
"version": 2,
"updated_at": "2023-05-30T00:16:23Z",
"value": false,
"created_at": "2023-05-20T20:20:35Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
},
"id1": {
"location_id": "7WQ0KXC8ZSD90",
"custom_attribute": {
"key": "general-manager",
"version": 3,
"updated_at": "2023-05-30T00:16:23Z",
"value": "Michael Francis",
"created_at": "2023-01-01T00:16:23Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
},
"id3": {
"errors": [
{
"code": "CONFLICT",
"detail": "Attempting to write to version 3, but current version is 4",
"field": "version",
"category": "INVALID_REQUEST_ERROR"
}
]
},
"id4": {
"location_id": "HF0HKANA3R9FP8",
"custom_attribute": {
"key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
"version": 2,
"updated_at": "2023-05-30T00:16:23Z",
"value": "[email protected]",
"created_at": "2022-11-08T23:14:47Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
}
}
After each custom attribute is upserted, Square invokes the location.custom_attribute.owned.updated
and location.custom_attribute.visible.updated
webhooks.
To list the custom attributes that are set for a location, call ListLocationCustomAttributes and provide the location_id
in the request path. The following parameters are optional:
with_definitions
- Indicates whether to return the custom attribute definition in thedefinition
field of each custom attribute. Set this parameter totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.limit
- Specifies a maximum page size of 100 results. The default limit is 20 results. If the results are paged, thecursor
field in the response contains a value that you can send with thecursor
query parameter to retrieve the next page of results.
The following example request includes the limit
query parameter:
List location custom attributes
When all pages are retrieved, the results include:
- All custom attributes owned by the requesting application that have a value. The
key
for these custom attributes is thekey
value that was provided for the definition. - All custom attributes owned by other applications that have a
value
and avisibility
setting ofVISIBILITY_READ_ONLY
orVISIBILITY_WRITE_VALUES
.
A custom attribute is owned by the application that created the corresponding definition.
The following is an example response:
{
"custom_attributes": [
{
"key": "general-manager",
"version": 2,
"updated_at": "2023-02-02T04:17:09Z",
"value": "Michael Francis",
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_ONLY"
},
{
"key": "repairs",
"version": 1,
"updated_at": "2023-01-20T02:41:37Z",
"value": false,
"created_at": "2023-01-20T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "minimum",
"version": 1,
"updated_at": "2022-12-02T19:51:29.235Z",
"value": 10,
"created_at": "2022-12-02T19:51:29.235Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "services-offered",
"version": 1,
"updated_at": "2022-12-06T15:57:23.211Z",
"value": ["610fa590-70cd-4ec9-b64c-1dad6ba3c8f9"
],
"created_at": "2022-12-06T15:57:23.211Z",
"visibility": "VISIBILITY_READ_ONLY"
}
]
}
To see the custom attribute definitions along with the custom attributes, set the with_definitions
query parameter to true
.
List location custom attributes
The following is an excerpt of an example response showing the custom attribute definition in the definition field:
{ "key": "repairs", "version": 1, "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" } "updated_at": "2023-01-20T02:41:37Z", "value": false, "created_at": "2023-01-20T02:41:37Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } ...
If no custom attributes are found, Square returns an empty object.
{}
To retrieve a custom attribute from a location, call RetrieveLocationCustomAttribute and provide the location_id
in the request path, along with the key
of the custom attribute to retrieve.
The following parameters are optional:
with_definition
- Indicates whether to return the custom attribute definition in thedefinition
field of the custom attribute. Set this parameter totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.version
- The current version of the custom attribute, 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
The response shows an Address
-type custom attribute. The value
field contains the value of the custom attribute.
{
"custom_attribute": {
"key": "businessAddress",
"version": 1,
"updated_at": "2022-05-26T17:08:57Z",
"value": {
"address_line_1": "333 2nd St",
"locality": "San Francisco",
"administrative_district_level_1": "California",
"postal_code": "94107",
"country": "US"
},
"created_at": "2022-05-26T17:08:57Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
To see the custom attribute definitions along with the custom attributes, set the with_definition
query parameter to true
:
Retrieve location custom attribute
The response shows the custom attribute definition in the definition
field. This example defines a Selection
-type custom attribute. The mapping information in the schema.items
field is used to determine the custom attribute value.
The names
field contains the named options and the enum
field contains the corresponding Square-assigned UUIDs. The named options map by index to the UUIDs. The first option maps to the first UUID, the second option maps to the second UUID, and so on. Therefore, the UUID in the value
field of this custom attribute maps to the "Reupholstery"
option.
{
"custom_attribute": {
"key": "services-offered",
"version": 2,
"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"
},
"updated_at": "2023-01-09T15:57:23.211Z",
"Value": [
"610fa590-70cd-4ec9-b64c-1dad6ba3c8f9"
],
"created_at": "2022-12-06T15:57:23.211Z",
"visibility": "VISIBILITY_READ_ONLY"
}
}
If the custom attribute isn't set for the specified location, Square returns the following response:
{
"errors": [
{
"code": "NOT_FOUND",
"detail": "The requested Value `{key}` is not found",
"category": "INVALID_REQUEST_ERROR"
}
]
}
If the custom attribute isn't available for the seller's locations, Square returns the following response:
{
"errors": [
{
"code": "BAD_REQUEST",
"detail": "No matching definition found for value",
"field": "key",
"category": "INVALID_REQUEST_ERROR"
}
]
}
To delete a custom attribute from a location, call DeleteLocationCustomAttribute and provide the location_id
in the request path, along with the key
of the custom attribute to delete. If the requesting application isn't the definition owner, the visibility
value of the definition must be VISIBILITY_READ_ONLY
or VISIBILITY_READ_WRITE_VALUES
.
Delete location custom attribute
If successful, Square returns an empty object.
{}
To delete all custom attributes of one or more locations in a single request, call the BulkDeleteLocationCustomAttributes endpoint.
After a custom attribute definition is deleted, Square invokes the location.custom_attribute.owned.deleted
and location.custom_attribute.visible.deleted
webhooks.