Shared Options and Modifiers Overview (Beta)

This overview introduces Shared Options and Modifiers using the Catalog API.

Introduction

Background

Some merchants have products that have the same options or modifiers. They may want to save time when creating or updating options or modifiers across products. For example, merchants may have multiple products they want shoppers to customize by size. If each product had the same sizes– small, medium, and large– merchants would save time by updating all the sizes simultaneously.

Feature

Shared Options and Modifiers are options or modifiers that you can share among products in the Catalog. You can create the option and assign it to multiple products. Changes made to a shared option affect all products associated with the option. 

The API allows you to create shared options and modifiers, but not assign them to products. At this time, assigning shared options and modifiers to products must be done through the control panel.

Target audience

This feature may benefit merchants with identical options or modifiers across products. Products can share an option if the entire option is identical– options must have the same default values, configuration, and more.

Concepts and terminology

Learn about the key concepts and features of shared options and modifiers below.

Shared option or modifier

A shared option or modifier is an option or modifier you can assign to multiple products in a catalog. 

Shared options have the same features as product variant options. Like variant options, they consist of the same types, Option Values, and more. Each shared option has a storefront name displayed to shoppers and a unique name displayed in the control panel. 

Likewise, shared modifiers have the same features as product modifiers. As with product modifiers, merchants may add adjustment rules to shared modifiers so that the overall product price or weight changes when a shopper selects the modifier. For more info on adjustment rules, see the Product Variant Options- Customizations (opens in a new tab) support article.

Type of shared option

There are multiple types of options available. For example, dropdown types allow shoppers to choose from a dropdown list. The storefront displays each type with a different style. For more information, see the Options and Modifiers- Types Support Article (opens in a new tab). 

The table below explains the types of shared options available. All options are multiple choice; shoppers select one from a list of values. Each choice in the list is an option value.

 

Type	Description
Dropdown	Multiple choice option that allows shoppers to choose from a dropdown list.
Rectangle List	Multiple choice option that allows shoppers to choose from a rectangular display list.
Radio Buttons	Multiple choice option that allows shoppers to choose from a radio button display list.
Swatch	Multiple choice option that allows shoppers to choose a color selection from a list. Each choice in the list is an option value that consists of one or more colors.

Type of shared modifier

There are multiple types of modifiers available. For example, modifiers that are text fields allow shoppers to enter text to customize the product. The storefront displays each type with a different style. For more information, see the Options and Modifiers- Types Support Article (opens in a new tab). 

The table below explains the types of shared options available. Some modifiers are multiple choice; shoppers select one value or choice from a list of values. Some types allow shoppers to enter text or input custom values to customize the product. Depending on the type of modifier, you may need to configure additional information. 

Type	Description	Additional configuration
Dropdown	Multiple choice modifier that allows shoppers to choose from a dropdown list. Each choice in the list is a modifier value.	None
Rectangle List	Multiple choice modifier that allows shoppers to choose from a rectangular display list. Each choice in the list is a modifier value.	None
Radio Buttons	Multiple choice modifier that allows shoppers to choose from a radio button display list. Each choice in the list is a modifier value.	None
Swatch	Multiple choice modifier that allows shoppers to choose a color selection from a list. Each choice in the list is a modifier value that consists of one or more colors.	None
Text field	Modifier that allows shoppers to input a single line of text into the text field.	You can require that the shopper enter a certain number of characters or limit the number of characters the shopper can enter. Permits a default value.
Date field	Modifier that allows shoppers to input a date.	You can require that the shopper enters a date before or after a specified date or within a range of dates. Permits a default value.
Numbers-only text field	Modifier that allows shoppers to input a number into the text field.	You can require that the shopper enters a number less or greater than a specified number or within a range of numbers. You can require that the number be an integer.Permits a default value.
Multi-line text field	Modifier that allows shoppers to input multiple lines of text into the text field.	Has the same configuration as Text field modifiers. In addition, you can limit the maximum number of lines a shopper can enter. Permits a default value.
Checkbox	Modifier that allows shoppers to choose whether to include the provided customization with the product.	State the label displayed with the checkbox modifier. Can be checked by default.
File upload	Modifier that allows shoppers to upload files used to customize the product.	You can specify the maximum size and types of files a shopper can upload.

Option or modifier values 

Option or modifier values are the choices available to shoppers for an option or modifier. For example, a dropdown size option may have small, medium, and large values. You can choose the order these values display on the storefront. 

Options and modifiers that are multiple choice, such as dropdowns, require values. Specifying a default value is optional. Those that are not multiple choice, such as text fields, may have a default value, but no other available choices.

Use cases 

You can perform the following with the API:

• Manage shared options and modifiers, including their configurations, display type, values, and more.

• Batch create and update shared options and modifiers.

• Filter the options and modifiers you retrieve by type, storefront name, and more.

• Retrieve data on how many products are associated with a shared option or modifier.

Assigning options and modifiers allows you to do the following: 

• Simultaneously manage options or modifiers across products. 

• Simplify a merchant’s catalog within a store. 

For example requests, see the Shared Options Guide and Shared Modifiers Guide. Assigning options and modifiers to products is out of scope of the API and must be done through the control panel.

Design context

The Shared Option and Shared Modifier endpoints in this beta are part of the Catalog API. The Catalog API also contains Product Variant Option and Product Modifier endpoints.

The Catalog API separates properties of options and modifiers that you can share from parameters of options and modifiers that belong to the product. Shared Option and Shared Modifier endpoints manage properties for shared options and shared modifiers; parameters that belong to the shared option or shared modifier fall under these endpoints. However, Product Variant Option and Product Modifier endpoints manage option or modifier settings that you can customize for individual products; these endpoints govern parameters that belong to the product.

For example, you cannot customize a shared modifier's display name for an individual product. You must use the Shared Modifier endpoints, not the Product Modifier endpoints, to manage the storefront display name. Changes apply to all products that use the shared modifier. Likewise, you cannot customize shared options at the product level.

However, adjustment rules for shared modifiers exist at the product level. This allows flexibility in the Catalog; you can customize rules for each product. Using this design, you must assign a shared modifier to a product before creating rules. Use the Product Modifier endpoints, not the Shared Modifier endpoints, to retrieve the rules that a product has for its shared modifiers. 

In addition, the sort order for a modifier is not a parameter of the shared modifier, but the product. Use the Product Modifier endpoints to manage sort orders. The same applies to shared options and their corresponding endpoints.

Limitations

The following limitations are to be determined in the beta phase:

• Maximum number of shared options or modifiers you can create, update, get, and delete per call
• Maximum number of shared option or modifier values you can create, update, get, and delete per call
• Maximum number of products to which you can assign an option or modifier
• Maximum number of shared options or modifiers that you can assign to a product

Resources

Guides and tutorials

• Shared Options Guide
• Shared Modifiers Guide
• Shared Options Support Article (opens in a new tab)
• Shared Modifiers Support Article (opens in a new tab)

API references

• Catalog API Reference- Shared Options and Modifiers

Shared options reference

• Create shared options
• Update shared options
• Get shared options
• Delete shared options
• Get a shared option

Shared modifiers reference

• Create shared modifiers
• Update shared modifiers
• Get shared modifiers
• Delete shared modifiers
• Get a shared modifier

Shared option values reference

• Create shared option values
• Update shared option values
• Get shared option values
• Delete shared option values
• Get a shared option value

Shared modifier values reference

• Create shared modifiers values
• Update shared modifiers values
• Get shared modifier values
• Delete shared modifiers values
• Get a shared modifier value