Creating Custom Attributes in Catalog

With an ever-increasing demand for contactless commerce, Square sellers have asked for help growing their digital sales. Sellers rely on the Catalog API to help them represent what they’re selling accurately, in whatever channel they make a sale. For developers building on Square’s platform, it’s common for integrations to require use-case specific or custom attributes that are not covered by Catalog API’s standard attributes (item name, SKU, price etc.). To enable this, we have released Catalog Custom Attributes to allow developers to create custom attribute definitions on Items and Variations via our API, improving the usefulness through increased flexibility.

Custom Attributes enables developers to associate additional information to ITEM and ITEM_VARIATION type catalog objects. For example, suppose a quick service restaurant integrates with an order ahead app. The order ahead app may need to get additional details from the seller such as whether or not the item is “Available for Delivery or Pickup”, a buyer friendly “Menu Name”, and a selection of applicable “Allergens” for every item in the Seller’s Catalog. To do this, the order ahead app can define custom attributes and assign them to all items in a Seller’s catalog. Based on the values entered by the seller in the Square Online Dashboard, the order ahead app can sync those details to its buyer-facing menu. The result: the order ahead app gets the information it needs to create a seamless integration and the seller can use Square Dashboard to manage their sales channels.

Catalog Custom Attributes support four data types: string, number, boolean, and a selection list. The selection list allows sellers to choose one or more values from a predefined list of values.

Since there are strong use cases for supporting custom attributes that are not visible to the seller (e.g. tokens unique to an external application), Catalog Custom Attributes also supports invisible attribute definitions. This allows developers to store seller-invisible values within Square Catalog. Additionally, a developer’s Custom Attributes are not limited to just one of their applications. With App Visibility settings, both seller-hidden and seller-visible custom attributes can be shared across developer accounts.

Using Catalog API for Custom Attributes

In the examples below, we use '#'-prefixed temporary ids, even across requests. In actual code, the caller would be given the real server-assigned id as part of the initial response to the object creation request, and would use that id in future requests.

Note: You do not want to be storing any kind of personally identifiable information (PII) inside of custom attributes. Please see our guide on Best Practices for Collecting Information for tips on how to handle customer data responsibly.

Create Custom Attribute Definitions

First, we'll show how to upsert two Custom Attribute Definitions, along with an Item and Item Variation that use them.

// POST /catalog/batch-upsert
{
  "idempotency_key": "{{$guid}}",
  "batches": [{
    "objects": [{
        "id": "#vintage",
        "type": "CUSTOM_ATTRIBUTE_DEFINITION",
        "custom_attribute_definition_data": {
          "name": "Vintage",
          "key": "vintage",
          "type": "NUMBER",
          "allowed_object_types": [
            "ITEM_VARIATION"
          ]
        }
      },
      {
        "id": "#tasting-notes",
        "type": "CUSTOM_ATTRIBUTE_DEFINITION",
        "custom_attribute_definition_data": {
          "name": "Tasting Notes",
          "key": "tasting-notes",
          "type": "SELECTION",
          "selection_config": {
            "max_allowed_selections": 100,
            "allowed_selections": [{
                "uid": "#anise",
                "name": "Anise"
              },
              {
                "uid": "#blackberries",
                "name": "Blackberries"
              },
              {
                "uid": "#chocolate",
                "name": "Chocolate"
              },
              {
                "uid": "#spicy-clove",
                "name": "Spicy Clove"
              },
              {
                "uid": "#tart-cherry",
                "name": "Tart Cherry"
              },
              {
                "uid": "#tobacco",
                "name": "Tobacco"
              },
              {
                "uid": "#vanilla",
                "name": "Vanilla"
              }
            ]
          },
          "allowed_object_types": [
            "ITEM_VARIATION"
          ]
        }
      },
      {
        "id": "#georges-duboeuf-beaujolais",
        "type": "ITEM",
        "item_data": {
          "name": "Georges duBoeuf Beaujolais",
          "variations": [{
            "id": "#georges-duboeuf-beaujolais-variation",
            "type": "ITEM_VARIATION",
            "custom_attribute_values": {
              "vintage": {
                "number_value": "2015"
              },
              "tasting-notes": {
                "selection_uid_values": [
                  "#tart-cherry",
                  "#spicy-clove",
                  "#tobacco"
                ]
              }
            },
            "item_variation_data": {
              "name": "Vintage 2015",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              }
            }
          }]
        }
      }
    ]
  }]
}

Edit the Custom Attribute

Next, we'll show how to edit the variation to change its name to "Vintage 2017" and change the "Vintage" Custom Attribute to 2017 as well.

// POST /catalog/object
{
  "idempotency_key": "{{$guid}}",
  "object": {
    "id": "#georges-duboeuf-beaujolais",
    "type": "ITEM",
    "custom_attribute_values": {
      "tasting-notes": {
        "selection_uid_values": [
          "#tart-cherry",
          "#spicy-clove",
          "#tobacco"
        ]
      }
    },
    "item_data": {
      "name": "Georges duBoeuf Beaujolais",
      "variations": [{
        "id": "#georges-duboeuf-beaujolais-variation",
        "type": "ITEM_VARIATION",
        "item_variation_data": {
          "name": "Vintage 2017",
          "pricing_type": "FIXED_PRICING",
          "price_money": {
            "amount": 2500,
            "currency": "USD"
          }
        },
        "custom_attribute_values": {
          "vintage": {
            "number_value": "2017"
          }
        }
      }]
    }
  }
}

We look forward to hearing from you as you use this new feature. We can’t wait to see what you build with this. Feel free to reach out to us in our developer community via chat or our forums with any questions or requests you may have.