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

Use Item Options to Manage Item Variations

Item variations are chargeable items related by certain variables. For example, a shirt is a product that can be represented by an item. However, a small red shirt is a chargeable product item with specified variations in size and color. The same is true for a large blue shirt. A seller can sell a shirt, which is represented by an item in the Catalog API, but the seller can only charge customers for a small red shirt or a large blue shirt, which is represented as an item variation in the API.

However, in an item variation, multiple parameters are combined into a single variable. This forces a related item variations into a flat ordered list, making it difficult to retrieve the item variations by a constituent variable, which is akin to random access to the targeted item variations.

You can use item options to manage related item variations by their constituent variables individually, which provides flexible and streamlined organization and retrieval of these objects. In this topic, you learn details about item variations and item options and how to restructure your catalog to use item options to manage item variations.

Item variations Permalink Get a link to this section

In previous versions of the Square catalog, products for sale are modeled as items and item variations. An item represents a type of product that can be sold while an item variation represents a particular object being sold. Typically, item variations are related items that can vary, for example, in name, description, SKU, price, inventory stock level, or any combination of such. Because prices can be set only on item variations, chargeable entries in an order must be item variations of the CatalogItemVariation type.

Each entry of the variations list is an item variation of either a simple one-dimensional parameter or a composite of multiple parameters as described in the preceding example. Simple item variations are powerful and easy to use, whereas composite item variations collapse multiple choices into a single choice and are awkward or unsuitable for display during the checkout flow. diagram-catalog-3

Create item variations related by size and color without item options Permalink Get a link to this section

To add item variations to a catalog, you create a (CatalogItem) instance with a list of CatalogItemVariation instances nested within the item through the variations attribute on the CatalogItem object.

Request Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "15e35296-47ff-49d0-9cc8-75b573ac3ea1",
    "object": {
      "id": "#shirt",
      "type": "ITEM",
      "item_data": {
        "description": "Shirt",
        "name": "Shirt",
        "product_type": "REGULAR",
        "variations": [
          {
            "id": "#shirt_small_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Small red shirt",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_medium_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Medium red shirt",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_large_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Large red shirt",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_small_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Small blue shirt",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_medium_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Medium blue shirt",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_large_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Large blue shirt",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ]
      }
    }
  }'

Response Permalink Get a link to this section

The request results in a CatalogItem instance with six CatalogItemVaration instances nested within.

{
  "catalog_object": {
    "type": "ITEM",
    "id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
    "updated_at": "2020-10-17T00:08:15.13Z",
    "version": 1602893295130,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Shirt",
      "description": "Shirt",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "F3P54C436KUEUGMRCUFYBEIZ",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Small red shirt",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 2500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "IJBAQDICELYUAUTHM352X3AI",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Medium red shirt",
            "ordinal": 1,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3000,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "5JMHD2SBPVG3A7ZFN5HDXSY6",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Large red shirt",
            "ordinal": 2,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "FQZGFI5ZQZY4RYK3H5X3QG2X",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Small blue shirt",
            "ordinal": 3,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 2500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Medium blue shirt",
            "ordinal": 4,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3000,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "H6QGZ6Q3XBEIL672DZYQW5SH",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Large blue shirt",
            "ordinal": 5,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3500,
              "currency": "USD"
            }
          }
        }
      ],
      "product_type": "REGULAR"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#shirt",
      "object_id": "3RJ4KVW64QXHXYDJ5CS6J4LE"
    },
    {
      "client_object_id": "#shirt_small_red",
      "object_id": "F3P54C436KUEUGMRCUFYBEIZ"
    },
    {
      "client_object_id": "#shirt_medium_red",
      "object_id": "IJBAQDICELYUAUTHM352X3AI"
    },
    {
      "client_object_id": "#shirt_large_red",
      "object_id": "5JMHD2SBPVG3A7ZFN5HDXSY6"
    },
    {
      "client_object_id": "#shirt_small_blue",
      "object_id": "FQZGFI5ZQZY4RYK3H5X3QG2X"
    },
    {
      "client_object_id": "#shirt_medium_blue",
      "object_id": "6F4K33KPNUVDWKZ43KUIFH6K"
    },
    {
      "client_object_id": "#shirt_large_blue",
      "object_id": "H6QGZ6Q3XBEIL672DZYQW5SH"
    }
  ]
}

Item options Permalink Get a link to this section

Item options let you structure item variations as a matrix of options instead of a flat ordered list. When a variation takes multiple parameters, you first create a CatalogItemOption instance for the variation parameter. Items are now associated with a list of item options and each item option defines a list of possible values.

Instead of using the variation's name attribute as the indexing parameter, you attach the list of the item option values to the item variation object through the item_option_values attribute. Item variations can then be indexed over the attached item option values. If the item_option_values list contains a single option, the resulting item variation is an order list. If the item_option_values list contains two options, the resulting item variations form a matrix. More generally, if the item_option_values list contains n options, the resulting item variation forms a tensor of rank n.

A given item option defines a single dimension of the item variation matrix. For example, consider a specific catalog item named T-shirt. A typical set of item options might be Size and Color, where the values for Size are Small, Medium, and Large and the values for Color are Red, Blue, and Yellow. Each item variation must be assigned a Size option and a Color option. Also, a given combination of Size and Color options can only be assigned to, at most, one item variation. In this way, you can organize the full set of item variations into a virtual item option matrix.

diagram-catalog-4@2x

Create item variations related by size and color with item options Permalink Get a link to this section

The following cURL example illustrates how to create item options similar to the preceding example.

Programmatically, the call proceeds by calling the BatchUpsertCatalogObject endpoint, first creating two CatalogItemOption objects and then creating a CatalogItem instance with six nested CatalogItemVariation objects. Attached to each CatalogItemVariation object are two item option values defining the supported colors (red and blue) and sizes (small, medium, and large).

Request Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "32378ef1-a9ae-4ca1-9614-38ce4921d35e",
    "batches": [
      {
        "objects": [
          {
            "id": "#item_option_color",
            "type": "ITEM_OPTION",
            "item_option_data": {
              "name": "COLOR_OPTIONS",
              "values": [
                {
                  "id": "#item_option_value_color_red",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "RED"
                  }
                },
                {
                  "id": "#item_option_value_color_blue",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Blue"
                  }
                }
              ]
            }
          },
          {
            "id": "#item_option_size",
            "type": "ITEM_OPTION",
            "item_option_data": {
              "name": "SIZE_OPTIONS",
              "values": [
                {
                  "id": "#item_option_value_size_small",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Small"
                  }
                },
                {
                  "id": "#item_option_value_size_medium",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Medium"
                  }
                },
                {
                  "id": "#item_option_value_size_large",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Large"
                  }
                }
              ]
            }
          },
          {
            "id": "#item",
            "type": "ITEM",
            "item_data": {
              "name": "Shirt",
              "product_type": "REGULAR",
              "item_options": [
                {
                  "item_option_id": "#item_option_size"
                },
                {
                  "item_option_id": "#item_option_color"
                }
              ],
              "variations": [
                {
                  "id": "#item_variation_small_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_small"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 2500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_medium_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_medium"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 3000,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_large_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_large"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 3500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_small_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_small"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 2500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_medium_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_medium"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 3000,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_large_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_large"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 3500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Notice how item option values are attached to an item variation by referencing relevant item option IDs and item option value IDs in the item_option_values attribute of an item variation.

Response Permalink Get a link to this section

The request results in the creation of:

  • Two item options (of CatalogItemOption): one for size and one for color.

  • One item (of CatalogItem).

  • Six item variations (of CatalogItemVariation) nested within the item. Each item variation references the size and color options by the corresponding item option value IDs defined in the two item option objects, respectively.

{
  "objects": [
    {
      "type": "ITEM_OPTION",
      "id": "GYWZZUMPQGBNMBANC32WWSWC",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_option_data": {
        "name": "COLOR_OPTIONS",
        "values": [
          {
            "type": "ITEM_OPTION_VAL",
            "id": "O7XQMPXSMFSGUSATAGARGX3E",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
              "name": "RED",
              "ordinal": 0
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "W55IT3LUEQI62LTLXOPLXYEL",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
              "name": "Blue",
              "ordinal": 1
            }
          }
        ]
      }
    },
    {
      "type": "ITEM_OPTION",
      "id": "WUHPNVNVCW2KBXZ36GT2BNZH",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_option_data": {
        "name": "SIZE_OPTIONS",
        "values": [
          {
            "type": "ITEM_OPTION_VAL",
            "id": "O55AQ6U4HFWDAIPHFHURPMEA",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Small",
              "ordinal": 0
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "RJI7UGDMDVOHBEQJSASTWOOJ",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Medium",
              "ordinal": 1
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "56QF4FR2BC2D67K4QJ2U2KYC",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Large",
              "ordinal": 2
            }
          }
        ]
      }
    },
    {
      "type": "ITEM",
      "id": "EQVBSUZZ65RO2WWPFU6PLYWU",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Shirt",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "6PRFCYBKD7QNDERVZP5FBDL7",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Small, RED",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "SOQTNT7336QXGHI3YK7ZZQ6O",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Small, Blue",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "KI66FNZXAEGEPE42J2PPX6AJ",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Medium, RED",
              "ordinal": 2,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "RHSUAWEXGNTQNQA55KNEYXOO",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Medium, Blue",
              "ordinal": 3,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Large, RED",
              "ordinal": 4,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "GBUW47ZH7I7PZI6E5XCWPLGD",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Large, Blue",
              "ordinal": 5,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          }
        ],
        "product_type": "REGULAR",
        "item_options": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC"
          }
        ]
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#item_option_color",
      "object_id": "GYWZZUMPQGBNMBANC32WWSWC"
    },
    {
      "client_object_id": "#item_option_size",
      "object_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
    },
    {
      "client_object_id": "#item",
      "object_id": "EQVBSUZZ65RO2WWPFU6PLYWU"
    },
    {
      "client_object_id": "#item_option_value_color_red",
      "object_id": "O7XQMPXSMFSGUSATAGARGX3E"
    },
    {
      "client_object_id": "#item_option_value_color_blue",
      "object_id": "W55IT3LUEQI62LTLXOPLXYEL"
    },
    {
      "client_object_id": "#item_option_value_size_small",
      "object_id": "O55AQ6U4HFWDAIPHFHURPMEA"
    },
    {
      "client_object_id": "#item_option_value_size_medium",
      "object_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
    },
    {
      "client_object_id": "#item_option_value_size_large",
      "object_id": "56QF4FR2BC2D67K4QJ2U2KYC"
    },
    {
      "client_object_id": "#item_variation_small_red",
      "object_id": "6PRFCYBKD7QNDERVZP5FBDL7"
    },
    {
      "client_object_id": "#item_variation_medium_red",
      "object_id": "KI66FNZXAEGEPE42J2PPX6AJ"
    },
    {
      "client_object_id": "#item_variation_large_red",
      "object_id": "AY6GSOG4ZZTYJ6RJPU2F4O6I"
    },
    {
      "client_object_id": "#item_variation_small_blue",
      "object_id": "SOQTNT7336QXGHI3YK7ZZQ6O"
    },
    {
      "client_object_id": "#item_variation_medium_blue",
      "object_id": "RHSUAWEXGNTQNQA55KNEYXOO"
    },
    {
      "client_object_id": "#item_variation_large_blue",
      "object_id": "GBUW47ZH7I7PZI6E5XCWPLGD"
    }
  ]
}

Notice that the name and ordinal attributes of an item variation are no longer set in the request. They are set on the item options. Do not set the name and ordinal attributes on the item variation when using an item option value. The ordinal number shown in the response is computed as the matrix element position. For an N x M matrix, the matrix element, m_(i,j) has the ordinal number of M*i+j, where i=0, ..., N-1 and j=0, ..., M-1.

Manage item variations with or without item options Permalink Get a link to this section

When an item option is used as part of an item variation, the display order for an item variation is determined by the order of the associated item option values. The display name for an item variation is derived by combining the names of the item option values associated with the item variation. You must manage the name and ordinal number of an item variation through the item option.

You can continue to manage the name and ordinal value on the item variations when not using item options. Other attributes, such as inventory counts and SKU, are still maintained at the item variation level regardless of whether item options are used.

Search for item variations using item options Permalink Get a link to this section

The following cURL example searches for the small and red item variation with item options defining the size and color. Notice that the item option values (Small and RED) are referred to by the respective item option value IDs (item_option_value_ids).

Request: Search for item variation by the item option values Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_types": [
      "ITEM"
    ],
    "query": {
      "item_variations_for_item_option_values_query": {
        "item_option_value_ids": [
          "O7XQMPXSMFSGUSATAGARGX3E",
          "O55AQ6U4HFWDAIPHFHURPMEA"
        ]
      }
    }
  }'

Response Permalink Get a link to this section

The request returns a successful response similar to the following. Because the request used the item_variations_for_item_option_values_query filter, only the matched item variations are returned.

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Request: Search for item variations by the RED item option value Permalink Get a link to this section

To specify the RED option value in the search query, set the RED item option value ID (O7XQMPXSMFSGUSATAGARGX3E) on the item_variation_for_item_option_values_query filter.

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_types": [
      "ITEM"
    ],
    "query": {
      "item_variations_for_item_option_values_query": {
        "item_option_value_ids": [
          "O7XQMPXSMFSGUSATAGARGX3E"
        ]
      }
    }
  }'

Response Permalink Get a link to this section

The successful response includes three item variations including the RED item option, namely, the Small, RED, Medium, RED, and Large, RED item variations.

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "KI66FNZXAEGEPE42J2PPX6AJ",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Medium, RED",
        "ordinal": 2,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 3000,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Large, RED",
        "ordinal": 4,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 3500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Search for item variations by searchable attribute Permalink Get a link to this section

The Catalog API supports various query filters to search for catalog objects. The name attribute is one of the searchable attributes.

The following cURL example illustrates how to search for item variations with "small red shirt" or "small red" set on their names:

Request Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small red shirt"
        ]
      }
    }
  }'

Instead of using the "Small red shirt" phrase as a single element of the keywords list, you can specify a three-element list in the text_query expression as shown. The result is the same.

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small",
          "red",
          "shirt"
        ]
      }
    }
  }'

Response Permalink Get a link to this section

In the example catalog, there is only one item variation with the name of "Small red shirt". The successful response returns this object for the match.

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "F3P54C436KUEUGMRCUFYBEIZ",
      "updated_at": "2020-10-17T00:08:15.13Z",
      "version": 1602893295130,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
        "name": "Small red shirt",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Request Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small",
          "red"
        ]
      }
    }
  }'

The order of the query expression list does not matter and punctuations are ignored.

Response Permalink Get a link to this section

In the example catalog, there is an item variation (named Small red shirt) without item options and another item variation (named Small, RED) with item option values defining the size and color. As the result, the previous request returns both for the match.

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "F3P54C436KUEUGMRCUFYBEIZ",
      "updated_at": "2020-10-17T00:08:15.13Z",
      "version": 1602893295130,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
        "name": "Small red shirt",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Migrate item variations to use item options Permalink Get a link to this section

You have three options to manage your catalog items.

Option 1: Continue to use your catalog as it currently exists Permalink Get a link to this section

If your item catalog does not need any structure beyond ordered lists and you do not need to update the name or ordinal field, you can continue to manage metadata for your item variations the same way you always have.

However, if you create new items that use item options or restructure existing items to use item options, you need to manage the name and ordinal fields at the item variation level.

Option 2: Keep existing items the same and use item options for new items Permalink Get a link to this section

If you want to use item options for some, but not all, of your catalog, you can maintain a combination of items that use the old item variation structure and items that use item options. Be aware however that items using item options cannot be managed the same way as items that use the old item variation model. Your code needs to differentiate between these two types of items. In particular, you need to manage name and ordinal information for your new items at the item option level.

Option 3: Restructure your entire catalog to use item options Permalink Get a link to this section

If you want to use item options for all your existing items, you need to restructure your product catalog.

  1. Use BatchRetrieveCatalogObjects to get the catalog object IDs for the catalog items you need to edit.

  2. Configure new item option objects using the name and ordinal fields from the existing item variations.

  3. Reference the item option values in the item variations.

  4. Set the name and ordinal field for the item variation to be null or blank.

  5. Send a BatchUpsertCatalogObjects request to update your catalog.

Step 1: Retrieve the item and item variations you want to restructure Permalink Get a link to this section

For example, suppose you retrieve an item (T-shirt) with three item variations that represent the sizes Small, Medium, and Large in the color Red:

{
  "catalog_object": {
    "type": "ITEM",
    ...
    "item_data": {
      "name": "T-shirt",
      ... 
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Small, Red",
      "ordinal": "1"

      ... 
      
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Medium, Red",
      "ordinal": "2"

      ... 
      
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Large, Red",
      "ordinal": "3"

      ... 
      
    }
  }
}

Step 2: Create item options Permalink Get a link to this section

Use the following cURL command to create two new item options. The BatchUpsertCatalogObjectsResponse returns item option value IDs that you can reference in your item variations in the next step.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2019-07-24' \
-d '{
  "idempotency_key": "b134aa8a-10ef-4eb8-886c-b16169ee5fd4",
  "batches": [
    {
      "objects": [
        {
          "id": "#shirt-size-item-option",
          "type": "ITEM_OPTION",
          "item_option_data":{
            "name": "T-Shirt Size",
            "display_name": "Size",
            "description": "Size for T-Shirts",
            "values":[
              {
                "id": "#shirt-size-small",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"S",
                  "display_name": "Small"
                }
              },
              {
                "id": "#shirt-size-medium",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"M",
                  "display_name": "Medium"
                }
              },
              {
                "id": "#shirt-size-large",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"L",
                  "display_name": "Large"
                }
              }
            ]
          }
        },
        {
          "id": "#shirt-color-item-option",
          "type": "ITEM_OPTION",
          "item_option_data":{
            "name": "T-Shirt Color",
            "display_name": "Color",
            "description": "Color for T-shirts",
            "values":[
              {
                "id": "#shirt-color-red",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"R",
                  "display_name": "Red"
                }
              },
              {
                "id": "#shirt-color-blue",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"B",
                  "display_name": "Blue"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}' \
'https://connect.squareup.com/v2/catalog/batch-upsert'

Step 3: Associate item variation with item option values Permalink Get a link to this section

Use the following cURL command to associate your item variations with these items and update the name and ordinal fields to null:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2019-07-24' \
-d '{
  "idempotency_key": "377814e3-8e12-4f9b-bf34-c9b5489a6cb9",
  "batches": [
    {
      "objects": [
        {
          "type": "ITEM",
          "id": "YBGUJQU6DFJG7TLVGZ7QHCKG",
          "updated_at": "2019-07-19T16:53:24.304Z",
          "version": 1563555204304,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_data": {
            "name": "T shirt",
            "visibility": "PRIVATE",
            "category_id": "FRZP2FQ2GTR76CNAVIKQ35EF",
            "item_options": [
              {
                "item_option_id": "SIZE_OPTION_ID"
              },
              {
                "item_option_id": "COLOR_OPTION_ID"
              }
            ],
            "product_type": "REGULAR",
            "skip_modifier_screen": false,
            "variations": [
              {
                "type": "ITEM_VARIATION",
                "id": "SMALL_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "MEDIUM_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              },
              {
                "type": "ITEM_VARIATION",
                "id": "MEDIUM_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "LARGE_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              },
              {
                "type": "ITEM_VARIATION",
                "id": "LARGE_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "LARGE_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}' \
'https://connect.squareupsandbox.com/v2/catalog/batch-upsert'