Define Custom Attributes for Locations

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.

Link to section

CustomAttributeDefinition object

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

Link to section

Create a location custom attribute definition

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.

Link to section

Selection data type

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 the https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json meta-schema hosted on the Square CDN.
type must be array.
items must include a names 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 the names field.
uniqueItems must be true.

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

Link to section

Update a location custom attribute definition

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 a Selection 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 the key 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 a BAD_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, the updated_at and version fields of the custom attributes are also updated. For VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES settings, the definition must have both a name and a description.

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.

Link to section

Updating a Selection schema

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 the names field.
To change the set of predefined named options, include the items field with the complete names and enum arrays. The options in the names array map by index to the Square-assigned UUIDs in the enum 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.
- 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.

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

Link to section

List location custom attribute definitions

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.

{}

Link to section

Retrieve a location custom attribute definition

Use the RetrieveLocationCustomAttributeDefinition endpoint to retrieve a custom attribute definition using its key. Note the following:

The key path parameter is the key 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 a 400 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.

Link to section

Delete a location custom attribute definition

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 the key 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.

Docs

Define Custom Attributes for Locations

CustomAttributeDefinition object

Create a location custom attribute definition

Selection data type

Update a location custom attribute definition

Did you know?

Updating a Selection schema

Note

List location custom attribute definitions

Retrieve a location custom attribute definition

Note

Delete a location custom attribute definition

On this page