Applies to: Catalog API
Learn how to restructure your catalog to use item options.
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. The following sections describe item variations and item options and how to restructure your catalog to use item options to manage item variations.
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.
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.
Upsert catalog object
The request results in a CatalogItem instance with six CatalogItemVariation 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"
}
]
}