Define Item Variations Using Options

Applies to: Catalog API

Learn how to use Item Options to simplify the process of creating many 'standard' variants for catalog items.

Utilizing item options can be a more effective strategy for application developers, particularly when dealing with sellers who lack consistency in naming item variations. By standardizing attributes such as size and color, item options streamline the search process. This approach enables users to easily locate specific product variations, such as a large, red polo shirt, without the confusion of sifting through inconsistently named entries like 'Large, red polo shirt', 'Red Polo shirt - LG', or 'Polo shirt: red, large'.

The Catalog API includes several objects that enable efficient and standardized definitions of item variations in the seller's inventory. These objects include:

• Items - Generalized items, e.g., "Shirt"
• Item variation - Specific items for sale, e.g., "Polo shirt: Lg, red"
• Item options - Standardized attributes like color, size, and style

When creating item variations in the Square Dashboard, sellers have two options: using item options or the variation name model. In both cases, the item_variation_data.name property is assigned a descriptive name. If item options are used, Square sets the variation name by combining the chosen option values into a comma-separated string, and the item_variation_data.item_option_values property references the selected options and values.

There are two strategies for defining shirt variations:

• Item variation name strategy - Add variation attributes to its name (e.g., "small red polo shirt").
• Item option strategy - Use item options to set variation attributes (e.g., "small", "red", "polo").

When the variation name strategy is used, a seller might give variations inconsistent names, as shown in these examples:

• "LG Red Camp Shirt"
• "Blue Polo shirt - small"
• "Yellow T-shirt: XL"

This can complicate searches within your application. For example, finding a blue polo shirt would involve a text query like "blue polo shirt" to locate the relevant catalog objects. For guidance on using a text query, see Search for item variations by searchable attribute.

Item options streamline the creation of item variations by linking them to standardized attributes, such as these examples:

• Color - Options include "Red", "Green", "Blue", etc.
• Size - Options range from "Extra Large" to "Small".
• Style - Varieties like "Polo", "Dress", "Camp", etc.

Once your application creates a CatalogItemOption like "color" with its values, that option can be used to define color for any new catalog items. Your application can also use catalog item options created by the seller in the Square Dashboard.

With item options, a variation is created for every combination of option values. Each variation is linked to options and values (like Red, Small, Polo), so sellers don't have to manually format each description. The examples given (color, size, style) are just that—examples. Your application can create any type of option with various values.

For details on querying by item option value, see Search for item variations using item options.

Item variations can be simple, featuring just one characteristic, or composite, which combine multiple characteristics.

In the following example, $35 polo shirts in three sizes and two colors are sold by a clothing retailer. To add these shirts to the catalog, six item variations are created. All have the same variation properties except for the variation name, which is unique to each variation.

• "Polo shirt, Red, Large"
• "Polo shirt, Red, Medium"
• "Polo shirt, Red, Small"
• "Polo shirt, Blue, Large"
• "Polo shirt, Blue, Medium"
• "Polo shirt, Blue, Small"

In the seller's item library and at the point of sale, items are organized alphabetically by name. If the naming of variations is inconsistent, the sorting order may appear illogical and confusing to the user.

To add item variations to a catalog, create a (CatalogItem) instance with a list of CatalogItemVariation instances nested within the item through the variations attribute on the CatalogItem object. A variation is created for each combination of color and size.

Continuing with the polo shirt example, a "Polo shirt" variation must have a color and size because the parent "Shirt" item was defined with these options. The possible values for these variation options are taken from the "Shirt" item definition.

Keep in mind that since "Polo shirt" and "Club shirt" are variations of "Shirt," they are restricted to the same option values. If the seller later receives teal polo shirts, they must add "Teal" to the color option set. Prices can be set for each variation, allowing for different styles to have distinct prices. For example, a "Shirt" item with "Polo shirt" and "Club shirt" variations can have the "Polo shirt" priced at $35 and the "Club shirt" at $45.

A seller might have already created a set of standard item options in the Square Dashboard. Before creating new options, you should see if the option you need is already available.

Your application can create the CatalogItem, CatalogItemOption objects, and the CatalogVariations objects with a single BatchCatalogUpsert call.

For the sake of simplicity in the following examples, the options are limited to color and size. The CatalogItemOption for "Style" is not used. Instead, the CatalogItem name is now "Polo Shirt" instead of the generic "Shirt".

The following example shows how to create item options similar to the previous example.

In the program, the process starts by using BatchUpsertCatalogObject to first create two CatalogItemOption objects. Then, a CatalogItem is created with nine CatalogItemVariation objects nested within it. Each CatalogItemVariation has two item option values attached, which specify the colors (red, blue, and yellow) and sizes (small, medium, and large).

When an item option is used in an item variation, the display order is determined by the sequence of the associated item option values. The display name for an item variation is created by combining the names of these option values. You must manage the name and order of an item variation through the item option.

If you're not using item options, you can still manage the name and order directly on the item variations. Other attributes, like inventory counts and SKU, are maintained at the item variation level, regardless of whether item options are used.

The following 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 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:

This query example uses only keywords that are common to multiple item variations, whether the variations were defined with item options or not.

In the example catalog, there's 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, this request returns both for the match.