Custom Attributes for Merchants

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 Merchant Custom Attributes API to extend the data model and associate seller-specific or application-specific information with merchants using your application. For example, you might want to store information such as the number of locations a merchant has, the business owner's name, or an email address.

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 Merchant Custom Attributes API consists of the following workflow:

1. Create a custom attribute definition for a merchant (Square seller).
2. Assign a custom attribute value to a merchant.
3. Retrieve custom attributes from merchants.

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

The following request creates a custom attribute definition to represent the name of a merchant's business owner. 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 sellers (merchants). The following UpsertMerchantCustomAttribute request sets the Business Owner custom attribute using the merchant_id and key. Note the following:

• The key in the path is business-owner, which is the same as the key specified by the definition.
• The value in the request body sets the custom attribute value for the merchant. 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 merchant.

The following RetrieveMerchantCustomAttribute request retrieves the Business Owner custom attribute for a merchant using the merchant_id and key in the request path:

The following is an example response:

{
  "custom_attribute": {
    "key": "business-owner",
    "version": 1,
    "updated_at": "2023-04-10T21:13:48Z",
    "value": "Adam Cortez",
    "created_at": "2023-04-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 Merchant Custom Attributes API supports the following operations:

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

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

Each custom attribute definition is scoped to a specific seller. Some Square APIs that use custom attributes (for example Customers or Bookings) allow you to make custom attributes available to multiple sellers that connect to your application with OAuth. However, because each Square seller is represented by a Merchant object, merchant custom attributes and their definitions cannot be shared between merchants.

You can subscribe to receive notifications for merchant-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 don't need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

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

{
  "merchant_id": "DM7VKY8Q63GNP",
  "type": "merchant.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": "business-owner",
    "object": {
      "created_at": "2023-01-20T02:41:37Z",
      "description": "The name of the business owner",
      "key": "business-owner",
      "name": "Business Owner",
      "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 merchants.custom_attribute.visible.updated notification:

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

• Define Custom Attributes for Merchants
• Use Custom Attributes for Merchants
• API Reference: Merchant Custom Attributes API