Add Custom Attributes

Applies to: Catalog API

Learn how to add custom attributes to your catalog objects and delete custom attribute definitions.

Custom attributes can be used to associate additional information with supported catalog objects. For example, a quick service restaurant uses an order-ahead application from a partner developer. The application needs additional information for each menu item:

• An application-specific menu item name, such as "Chicken" instead of the original item name of "CHK".
• An application-specific price.
• Allergen information.

Because catalog items don't have properties for this information, the seller can have custom attributes added to a CatalogItem object in their catalog to capture the additional details.

The following catalog object types can accept custom attributes:

• ITEM - Attributes are visible in the Square Dashboard and the API.
• ITEM_VARIATION - Attributes are visible in the Square Dashboard and the API.
• MODIFIER (2023-04-19 or later) - Attributes are visible only with the API.
• MODIFIER_LIST (2024-04-17 or later) - Attributes are visible only with the API.
• CATEGORY (2024-04-17 or later) - Attributes are visible only with the API.

• Each Square account can have up to 10 seller-visible and 10 seller-hidden custom attributes.
• You cannot edit the source_application, type, key, max_allowed_selections, or allowed_object_types of a custom attribute after creation.
• You cannot edit the configuration for STRING type attributes after creation.
• Custom attributes are available for Square version 2020-03-25 or later.

A catalog custom attribute has two parts: a definition and a set of values that can be empty. A value can be saved after the definition is set for supported object types. After a custom attribute definition is set to be applicable to an object, such as a CatalogItem or CatalogItemVariation, that definition is available for all objects of that type.

In the Square Dashboard, the seller edits an item to input a custom attribute value. A seller sees placeholders for all available definitions in every supported object even if values haven't yet been assigned.

Suppose a seller creates the following custom attribute definitions and allows them for items and item variations unless otherwise noted:

• Brand
• Components Brand
• Filling types
• Helmet Brand
• Shoe Brand
• Shoelace types - item variation only
• Tasting Notes
• Tea Brand

Because most of the definitions can be set on items and item variations, they appear on every item and item variation in the seller's catalog.

The following image from the Square Dashboard shows a shoelace item variation with a selected value for "Shoelace types" and no values for any other custom attributes.

The CatalogItemVariation for the shoelaces has a custom_attribute_values property like the following example:

curl https://connect.squareupsandbox.com/v2/catalog/object \
 -X POST \
 -H 'Square-Version: 2025-02-20' \
 -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -d '{
 "idempotency_key": "f1c31066-7b94-4d32-90a6-12a4398f1406",
 "object": {
   "type": "ITEM_VARIATION",
   "id": "HXSNEZN7N3NBGJX2XJ2Z6R5Q",
   "updated_at": "2025-02-19T23:20:25.835Z",
   "created_at": "2024-08-29T17:34:20.395Z",
   "version": 1740007225835,
   "is_deleted": false,
   "custom_attribute_values": {
     "Shoelace_Types": {
       "name": "Shoelace types",
       "custom_attribute_definition_id": "RLBNUGHJ3CVQXXUV37VMFYZW",
       "type": "SELECTION",
       "selection_uid_values": [
         "INYXXB6WEZVCPM3AMD343LY2"
       ],
       "key": "Shoelace_Types"
     }
   },
   "present_at_all_locations": true,
   "item_variation_data": {
     "item_id": "QWNIQEIK4VSPPQHEKZOZ4EYJ",
     "name": "8'' laces",
     "ordinal": 1,
     "pricing_type": "FIXED_PRICING",
     "price_money": {
       "amount": 234,
       "currency": "USD"
     },
     "location_overrides": [
       {
         "location_id": "E78VDDVFW1EYX",
         "track_inventory": false
       },
       {
         "location_id": "LFF3HK0DN6A61",
         "track_inventory": false
       }
     ],
     "track_inventory": false,
     "measurement_unit_id": "QTSYO4OCO6RIV2UWZOP6BRLV",
     "sellable": true,
     "stockable": true
   }
 }
}'

Note that the item doesn't show custom attributes for the definitions that don't have values.

The custom_attribute_values property of a catalog object is a key/value pair, allowing you to add an attribute value for each custom attribute you define. For example, you might add custom attributes to a bicycle item variation. Modifiers like size and color should be buyer-selectable and visible at the point of sale. You might also associate the brand of a component group by creating custom attribute definitions for the component brand and ID.

{
  "custom_attribute_values": {
     "component_brand": {
        "key": "component_brand",
        "custom_attribute_definition_id": "IQN73SQGHTOWP4JKZQNQDSKB",
        "name": "Brand",
        "type": "STRING",
        "string_value": "Shimano"
     }
  }
}

Because custom_attribute_values is a map, you need to define a map key, such as component_brand. This key string should match the key assigned to the custom attribute definition. Additionally, set the key field in the map object to the same string as the map key.

An application can create up to 10 seller-visible custom attribute definitions defined by a CatalogCustomAttributeDefinition object. Custom attribute definitions appear on the Edit Item page in the Square Dashboard, where people with sufficient permissions can see and edit the custom attribute values.