Learn how to add custom attributes to your catalog objects.
Catalog API

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

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

  • A partner-specific menu item name, such as "Chicken" instead of the original item name of "CHK".

  • A partner-specific price.

  • Allergen information.

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

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

Each application linked to a seller 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 in the Seller Dashboard, where sellers can see and edit the custom attribute values.

Note

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

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

You can control the visibility of a custom attribute by setting the CatalogCustomAttributeDefinition app_visibility and seller_visibility fields.

Note that the application 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.

The app_visibility field controls whether the custom attribute is readable or writable by other applications:

  • APP_VISIBILITY_READ_ONLY. Visible and searchable by other applications.

  • APP_VISIBILITY_READ_WRITE_VALUES. Other applications can read and write custom attribute values on objects.

  • APP_VISIBILITY_HIDDEN. Other applications cannot see APP_VISIBILITY_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 application or the Seller Dashboard:

  • SELLER_VISIBILITY_READ_WRITE_VALUES. Sellers can search and edit the custom attribute. For example, an application can define a custom attribute definition and set seller_visibility to SELLER_VISIBILITY_READ_WRITE_VALUES. This way, sellers are able to write values of the custom attribute and read them from the Seller Dashboard. Sellers can also search for this custom attribute, which might be useful for storing data for which the seller is intended to be the source of truth.

  • SELLER_VISIBILITY_HIDDEN. Sellers cannot see custom attribute definitions or the associated values.

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

Limitations include:

  • Each CatalogCustomAttributeDefinition object of the SELECTION type can define up to 100 allowed selection values.

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

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

Each custom attribute with the 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).

A true or false value. For example, BOOLEAN type custom attributes can be used to set whether an item is available for delivery in a third-party delivery application.

To use custom attributes, you 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 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 in the Seller Dashboard.

Batch Upsert Catalog Objects
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78
  • 79
  • 80
  • 81
  • 82
  • 83
  • 84
  • 85
  • 86
  • 87
  • 88
  • 89
  • 90
  • 91
  • 92
  • 93
  • 94
  • 95
curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "batches": [
      {
        "objects": [
          {
            "id": "#cocoa_brand",
            "type": "CUSTOM_ATTRIBUTE_DEFINITION",
            "custom_attribute_definition_data": {
              "allowed_object_types": [
                "ITEM",
                "ITEM_VARIATION"
              ],
              "name": "Brand",
              "type": "STRING",
              "key": "cocoa_brand"
            }
          },
          {
            "id": "#topping",
            "type": "CUSTOM_ATTRIBUTE_DEFINITION",
            "custom_attribute_definition_data": {
              "allowed_object_types": [
                "ITEM",
                "ITEM_VARIATION"
              ],
              "name": "Tasting Notes",
              "type": "SELECTION",
              "key": "topping",
              "selection_config": {
                "allowed_selections": [
                  {
                    "name": "Marshmallow",
                    "uid": "#marshmallow"
                  },
                  {
                    "name": "Whipped Cream",
                    "uid": "#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",
                "type": "STRING",
                "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"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

To delete a custom attribute from the catalog, call the DeleteCatalogObject endpoint while supplying the custom attribute ID as the object_id path parameter value. In the following example, the custom attribute object ID is assumed to be VEER7NOZJRW75LXVVVS4BX25:

Delete Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/catalog/object/VEER7NOZJRW75LXVVVS4BX25 \
  -X DELETE \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

  • Each seller 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.

We've made improvements to our docs.
Prefer the old format?