Learn how to create and manage custom attributes for locations using the Location Custom Attributes API.
Location Custom Attributes API

Custom Attributes for Locations Beta release
This is pre-release documentation for an API in public beta and is subject to change.

Custom attributes store additional properties or metadata about certain objects in the Square data model, allowing you to extend the functionality of your applications. Use the Location Custom Attributes API to extend the data model and associate seller-specific or application-specific information with locations. For example, merchants using your application might want to store information such as the general manager for a location, whether a particular location can take consignments, or the types of repairs offered at a location.

A custom attribute obtains a key identifier, the visibility setting, allowed data types, and other properties from a custom attribute definition. This relationship is shown in the following diagram:

A diagram showing a custom attribute definition for "general manager" used by custom attributes on multiple locations.

Note

Working with custom attributes is different than working with native attributes on the Location object (such as business_hours or phone_number) that are accessed using the Locations API. For example, custom attributes are not returned in a RetrieveLocation or ListLocations response or managed using CreateLocation or UpdateLocation.

Using the Location Custom Attributes API consists of the following workflow:

  1. Create a custom attribute definition for a seller.

  2. Assign a custom attribute value to a location.

  3. Retrieve custom attributes from locations.

To create a location-related custom attribute, you must first define its properties by calling CreateLocationCustomAttributeDefinition.

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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/locations/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "key": "general-manager",
      "visibility": "VISIBILITY_READ_WRITE_VALUES",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
      },
      "name": "General Manager",
      "description": "The General Manager at this Location"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The key identifier and visibility setting specified in the definition are used by the corresponding custom attributes. The visibility setting determines the access level that other applications (including other Square products) have to the definition and corresponding custom attributes.

After the custom attribute definition is created, you create new custom attributes and assign them to specific seller locations. The following UpsertLocationCustomAttribute request sets the General Manager custom attribute using the location_id and key. Note the following:

  • The key in the path is general-manager, which is the same as the key specified by the definition.

  • The value in the request body sets the custom attribute value for the location. This value must conform to the data type specified by the schema field in the definition. In this case, it is a String.

Upsert Location Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/locations/{location_id}/custom-attributes/general-manager \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "Christine Lee"
    }
  }'

Note

Square also provides the BulkUpsertLocationCustomAttributes endpoint to update multiple custom attributes on locations in a single request.

You can now retrieve the custom attribute to get the value that was set for the location.

The following RetrieveLocationCustomAttribute request retrieves the General Manager custom attribute for a location using the location_id and key in the request path:

Retrieve Location Custom Attribute
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/locations/{location_id}/custom-attributes/{key} \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

You can optionally include the with_definition query parameter to return the corresponding custom attribute definition in the same call. For example, you might want to retrieve the definition to get the custom attribute's data type, name, or description.

The Location Custom Attributes API supports the following operations:

Each custom attribute definition is scoped to a specific seller. Creating a definition makes the corresponding custom attribute available to any of that seller's locations. To make the custom attribute available to other sellers, you must call CreateLocationCustomAttributeDefinition on behalf of each target seller. To do so when using OAuth, call this endpoint for each seller using their access token.

The following diagram shows two sellers using identical general-manager custom attribute definitions to record their general manager locations:

A diagram showing two sellers using the same custom attribute definition to record the general manager at each of their locations.

You can reuse the same key for your custom attribute definition across sellers. The key must be unique for your application but not for a given seller.

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.

You can subscribe to receive notifications for location-related custom attribute events. Each event provides two options that allow you to choose when Square sends notifications:

  • .owned event notifications are sent when changes are made to custom attribute definitions and custom attributes that are owned by your application. A custom attribute definition is owned by the application that created it. A custom attribute is owned by the application that created the corresponding custom attribute definition.

  • .visible event notifications are sent when changes are made to custom attribute definitions and custom attributes that are visible to your application. These changes apply to:

    • All custom attribute definitions and custom attributes owned by your application.

    • All other custom attribute definitions or custom attributes whose visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

Notification payloads for both options contain the same information.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event
Permission
Description
location.custom_attribute_definition.owned.createdMERCHANT_PROFILE_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
location.custom_attribute_definition.owned.updatedMERCHANT_PROFILE_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
location.custom_attribute_definition.owned.deletedMERCHANT_PROFILE_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
location.custom_attribute.owned.updatedMERCHANT_PROFILE_READA custom attribute owned by your application was created or updated for a location.
location.custom_attribute.owned.deletedMERCHANT_PROFILE_READA custom attribute owned by your application was deleted from a location.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application. Therefore, you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event
Permission
Description
location.custom_attribute_definition.visible.createdMERCHANT_PROFILE_READA custom attribute definition that is visible to your application was created.
location.custom_attribute_definition.visible.updatedMERCHANT_PROFILE_READA custom attribute definition that is visible to your application was updated.
location.custom_attribute_definition.visible.deletedMERCHANT_PROFILE_READA custom attribute definition that is visible to your application was deleted.
location.custom_attribute.visible.updatedMERCHANT_PROFILE_READA custom attribute that is visible to your application was created or updated for a location.
location.custom_attribute.visible.deletedMERCHANT_PROFILE_READA custom attribute that is visible to your application was deleted from a location.

Note

Upserting or deleting a custom attribute for a location does not invoke a location.updated webhook.

The following is an example location.custom_attribute_definition.visible.created notification:

The following is an example locations.custom_attribute.visible.updated notification:

Note

Custom attributes are a feature shared by multiple Square APIs. For general information common to all Square APIs that support custom attributes, see Custom Attributes Overview.