Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Catalog API

Add Custom Attributes

Catalog API

Custom attributes let you associate additional information to ITEM and ITEM_VARIATION type catalog objects. For example, suppose a quick service restaurant hires an order-ahead manager. The order-ahead partner needs additional information for each menu item for example:

  • A buyer facing name (for example, "Chicken" instead of "CHK").

  • A partner specific price.

  • Allergen information.

You can add a custom attribute to any Item object in the restaurant catalog so the seller can track those additional details.

Seller visible custom attributes appear within the Item Library and Service Library on the Square Dashboard, allowing sellers to leverage Square as a one-stop shop for managing their information.

How it works
Permalink Get a link to this section

Each application attached to a seller's account can create up to 10 seller-visible custom attribute definitions defined by a CatalogCustomAttributeDefinition object. Custom attribute definitions appear in the Item Edit sheet on the Square Dashboard, where sellers are able to see and edit the custom attribute values.

Note

Custom attributes do not currently appear in the Square Point of Sale API.

Assigning a custom attribute definition to an item or variation means that it will appear on every object of that type within the seller’s catalog. For example, if a seller has a custom attribute to represent pizza toppings, every item in that seller’s catalog (including sodas) will have the toppings attribute.

Visibility
Permalink Get a link to this section

You can control a custom attribute’s visibility by setting the app_visibility field and the seller_visibility field in the custom attribute definition. The app_visibility field controls whether the custom attribute is readable or writable by other apps. Note that the app that created a custom attribute definition always has the ability to retrieve, search, and update the values of any custom attribute that uses that definition.

Options for app_visibility:

  • READ_ONLY. Not visible, searchable, or writeable by other apps.

  • READ_WRITE_VALUES. Other apps can edit values assigned to catalog objects, but cannot edit the definition. Only the source app can edit the definition.

  • HIDDEN. Other apps cannot see HIDDEN custom attribute definitions or the associated values.

The seller_visibility field controls whether the custom attribute appears in the UI of Square products, such as the Square Point of Sale app or Square Dashboard.

Options for seller_visibility:

  • READ_WRITE_VALUES. The seller can search and edit the custom attribute. For example, an app can define a custom attribute definition and set seller_visibility to EDITABLE_BY_SELLER. This way, sellers are able to write the values of the custom attribute in items that are visible to them on the Dashboard. Sellers can also search for this custom attribute. This might be useful for storing data for which the seller is intended to be the source of truth.

  • HIDDEN. Sellers cannot see HIDDEN custom attribute definitions or the associated values. You can create up to 10 custom attributes with seller_visibility set to HIDDEN, in addition to the 10 seller-visible custom attributes.

Types of custom attributes
Permalink Get a link to this section

Selection
Permalink Get a link to this section

A SELECTION type custom attribute has multiple possible values defined by the developer. SELECTION type attributes can also allow single or multiple value selections.

Limitations:

  • Each SELECTION type custom attribute definition can have up to 100 allowed selection values.

  • Each item or item variation can have up to 100 active selection values.

String
Permalink Get a link to this section

A STRING type custom attribute can take any freeform string value of up to 255 characters. The string value can include any Unicode code point. Empty strings are also allowed.

Number
Permalink Get a link to this section

Each custom attribute with NUMBER type can store values with up to 5 decimal places and can support values up to approximately 90 trillion (exact value 263/100,000).

Boolean
Permalink Get a link to this section

A true or false value. Developers can set the default value to be true or false.

As an example, BOOLEAN type custom attributes can be used to set whether an item is available for delivery in a third-party delivery app.

Requirements and limitations
Permalink Get a link to this section

  • Each merchant can have up to 10 seller-visible and 10 non-seller-visible custom attributes.

  • You cannot edit the type of a custom attribute after creation.

  • You cannot edit the configuration for STRING type attributes after creation.

  • You must use Square Version “2020-03-25” to work with custom attributes in beta.

Add a custom attribute to a catalog object
Permalink Get a link to this section

To use custom attributes, you’ll need to:

  1. Create a CatalogObject of the CUSTOM_ATTRIBUTE_DEFINITION type. This determines the type of custom attribute and the visibility.

  2. Add the custom attribute to a catalog item.

In the following example, a custom attribute definition is created for a custom field to track what brand of cocoa is used for a Hot Cocoa item. This custom attribute takes STRING values. You will specify a key that you can use to identify this custom attribute definition in the next step.

Important

You need to specify the allowed_object_types for your new custom attribute definitions to be displayed on the Dashboard.

curl https://connect.squareup.com/v2/catalog/batch-upsert\
  -X POST \
  -H 'Square-Version: 2020-03-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
  "idempotency_key": "UNIQUE_STRING",
  "batches": [
    {
      "objects": [
        {
          "id": "#cocoa_brand",
          "type": "CUSTOM_ATTRIBUTE_DEFINITION",
          "allowed_object_types": ["ITEM", "ITEM_VARIATION"],
          "custom_attribute_definition_data": {
            "name": "Brand",
            "key": "cocoa_brand",
            "type": "STRING"
          }
        },
        {
          "id": "#topping",
          "type": "CUSTOM_ATTRIBUTE_DEFINITION",
          "custom_attribute_definition_data": {
            "name": "Tasting Notes",
            "key": "topping",
            "type": "SELECTION",
            "selection_config": {
              "allowed_selections": [
                {
                  "uid": "#marshmallow",
                  "name": "Marshmallow"
                },
                {
                  "uid": "#whipped-cream",
                  "name": "Whipped Cream"
                }
              ],
              "max_allowed_selections": 5
            }
          }
        },
        {
          "id": "#hot-cocoa",
          "type": "ITEM",
          "custom_attribute_values": {
            "cocoa_brand": {
              "key": "cocoa_brand",
              "custom_attribute_definition_id": "#cocoa_brand",
              "name": "Brand",
              "string_value": "Cocoa Magic"
            }
          },
          "item_data": {
            "name": "Hot Cocoa",
            "variations": [
              {
                "id": "#hot-cocoa-small",
                "type": "ITEM_VARIATION",
                "custom_attribute_values": {
                  "topping": {
                    "key": "topping",
                    "custom_attribute_definition_id": "#topping",
                    "name": "Tasting Notes",
                    "type": "SELECTION",
                    "selection_uid_values": [
                      "#marshmallow",
                      "#whipped-cream"
                    ]
                  }
                },
                "item_variation_data": {
                  "name": "Small",
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
} 
' 

Update custom attribute
Permalink Get a link to this section

The following example changes the STRING-type custom attribute for our hot cocoa item to Flavor instead of Brand. Note that the temporary ID used in the previous example will be replaced with the ID returned when the custom attribute was created.

POST /v2/catalog/object

curl https://connect.squareup.com/v2/catalog/object\
  -X POST \
  -H 'Square-Version: 2020-03-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    "idempotency_key": "UNIQUE_STRING",
      "object":
        {
          "id": "COCOA_BRAND_ID",
          "type": "CUSTOM_ATTRIBUTE_DEFINITION",
          "custom_attribute_definition_data": {
            "name": "Flavor",
            "type": "STRING"
          }
        }
    }'


Delete custom attribute from an item or variation.
Permalink Get a link to this section

Send a DELETE request to the following endpoint. You will need to set the custom attribute ID as a path parameter.

DELETE /v2/catalog/object/CUSTOM_ATTRIBUTE_ID