Custom Attributes for Locations

Applies to: Location Custom Attributes API | Locations API

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

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:

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.

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's a String.

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:

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

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.

• Create a location custom attribute definition
• Update a location custom attribute definition
• List location custom attribute definitions
• Retrieve a location custom attribute definition
• Delete a location custom attribute definition

• Create or update a location custom attribute
• Bulk create or update location custom attributes
• List location custom attributes
• Retrieve a location custom attribute
• Delete a location custom attribute
• Bulk delete location custom attributes

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:

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.

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:

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.

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

{
  "merchant_id": "DM7VKY8Q63GNP",
  "type": "location.custom_attribute_definition.visible.created",
  "event_id": "347ab320-c0ba-48f5-959a-4e147b9aefcf",
  "created_at": "2023-01-20T02:41:37Z",
  "data": {
    "type": "custom_attribute_definition",
    "id": "general-manager",
    "object": {
      "created_at": "2023-01-20T02:41:37Z",
      "description": "Work email address",
      "key": "general-manager",
      "name": "General Manager",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
      },
      "updated_at": "2023-01-20T02:41:37Z",
      "version": 1,
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  }
}

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

{
  "merchant_id": "DM7VKY8Q63GNP",
  "type": "locations.custom_attribute.visible.updated",
  "event_id": "1cc2925c-f6e2-4fb6-a597-07c198de59e1",
  "created_at": "2023-03-15T08:00:00Z",
  "data": {
    "type": "custom_attribute",
    "id": "general-manager",
    "object": {
      "created_at": "2023-01-20T02:41:37Z",
      "key": "general-manager",
      "updated_at": "2023-03-15T08:00:00Z",
      "value": "Michael Francis",
      "version": 2,
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  }
}

• Define Custom Attributes for Locations
• Use Custom Attributes for Locations
• API Reference: Location Custom Attributes API