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.
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.
The request results in a CatalogItem
instance with six CatalogItemVariation
instances nested within.
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.
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).
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.
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.
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
.
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.
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
).
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.
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.
The successful response includes three item variations including the RED
item option, namely, the "Small, RED
," "Medium, RED
," and "Large, RED
" item variations.
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:
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.
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.
The order of the query expression list does not matter and punctuations are ignored.
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.
You have three options to manage your catalog items.
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.
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.
If you want to use item options for all your existing items, you need to restructure your product catalog.
Use
BatchRetrieveCatalogObjects
to get the catalog object IDs for the catalog items you need to edit.Configure new item option objects using the
name
andordinal
fields from the existing item variations.Reference the item option values in the item variations.
Set the
name
andordinal
field for the item variation to benull
or blank.Send a
BatchUpsertCatalogObjects
request to update your catalog.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.