Catalog - Product modifiers
The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.
Product modifiers represent choices that the shopper can make to change how the merchant customizes or adds on to the product. Examples include shipping insurance, monograms, custom inseam length, and color selections for unfinished products.
Modifier values do not change which item is picked in a warehouse, but they change what happens to that item between the warehouse shelf and the shopper taking possession of their order.
Critically, modifier values do not change which product variant is fulfilled. You cannot track inventory for combinations of modifier values.
You can add an adjuster to a modifier value to override the underlying product variant's properties, such as price, weight, and shipping rules. Not all modifier types are compatible with adjusters.
To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.
Option Values and Configs
Modifiers endpoints include many fields with data that are specific to one or more type values, as different modifier option types have different functionality. This information is contained in the option_values array and the config object. See the tables below for details on the fields available for each modifier type.
Option Values
Modifier types that present choices to the shopper use an option_values array. Each entry defines a possible value for that modifier, along with display text, ordering, and adjusters for price, weight, and more. This is not used for modifier types that do not present choices, including text, multi_line_text, numbers_only_text, date, and file.
| Field | Description | Applies to Types |
|---|---|---|
is_default | Whether this value is selected by default; not supported by the swatch type | All with options (except swatch) |
label | Storefront display text for the option value | All with options |
sort_order | Display order of the value on product pages | All with options |
value_data |
| swatch, product list, product list with images, checkbox |
adjusters.price | Price adjustment for complex rules. Defines whether the price adjustment is relative (fixed) or percentage, and sets the amount to adjust the price. | All with options |
adjusters.weight | Weight adjustment for complex rules on physical products. Defines whether the weight adjustment is relative (fixed) or percentage, and sets the amount to adjust the weight. | All with options |
adjusters.image_url | The full URL path for the image displayed when the value is selected on the storefront product page. The image file can have a maximum size of 8 MB. | All with options |
adjusters.purchasing_disabled | Defines whether or not the option value is purchasable. If purchasing is disabled, you can specify a message to appear when the value is selected on the storefront. | All with options |
id | Unique numeric ID for the option value; not used in /POST requests | All with options |
option_id | Modifier ID this value belongs to | All with options |
Configs
The config object customizes the behavior and validation of a modifier. Available fields depend on the type of modifier, such as text, date, file, or product list. Note that the multiple choice option types (radio_buttons, rectangles, dropdown, swatch) do not have option configs, as they only use fields in the option_values array.
| Modifier Type(s) | Config Field | Description or Values |
|---|---|---|
date | default_value | Default ISO date string |
date_limited | Boolean: Indicates whether the allowed date options are limited | |
date_limit_mode | Defines the type of limit on the date option. Accepts earliest, range, and latest. | |
date_earliest_value | ISO date: the earliest date allowed to be entered on the date option | |
date_latest_value | ISO date: the latest date allowed to be entered on the date option | |
checkbox | checked_by_default | Boolean: Indicates whether the option is checked by default |
checkbox_label | The label that appears next to the checkbox on the storefront | |
file | file_types_mode | Specifies whether you want to allow shoppers to upload any file type or if you only want to accept particular types defined in the file_types_supported array. |
file_types_supported | Specifies groups of file types to accept for upload. See Supported File Types to learn more. | |
file_types_other | List specific file types to accept for upload | |
file_max_size | Integer: the max file size in KB to accept for upload. This cannot exceed 524,288 KB. | |
text, multi_line_text | default_value | String: the default value that appears in the text box |
text_characters_limited | Boolean: Indicates whether the field validates the character count with a minimum and maximum value | |
text_min_length | Integer: Specifies the minimum allowed characters | |
text_max_length | Integer: Specifies the maximum allowed characters | |
multi_line_text | text_lines_limited | Boolean: Indicates whether the field limits the number of text lines |
text_max_lines | Integer: Specifies the maximum allowed lines | |
numbers_only_text | default_value | String/number: the default value that appears in the number box |
number_limited | Boolean: Indicates whether the field validates the entered number with a minimum and maximum value | |
number_limit_mode | Defines the type of limit on the number option. Accepts lowest, range, and highest. | |
number_lowest_value | Number: Specifies the minimum value | |
number_highest_value | Number: Specifies the maximum value | |
number_integers_only | Boolean: Indicates whether the field accepts decimals or whole numbers only | |
product_list, product_list_with_images | product_list_adjusts_inventory | Indicates whether selecting and purchasing a product in the list adjusts that product's inventory |
product_list_adjusts_pricing | Indicates whether selecting a product in the list adds its price to the main product's price | |
product_list_shipping_calc | Specifies how to factor weight and package dimensions when selecting a product in the list. Use weight to add the list product's weight to the main product, package to add the list product's weight and dimensions, or none to not adjust the main product's weight and dimensions. |
Supported File Types
The file modifier type allows you to restrict the file types that can be uploaded by a shopper by setting the file_types_mode to specific. You can then use the file_types_supported and file_types_other arrays to specify the allowed file types. The following file types are supported:
| File Type Category | Included File Types |
|---|---|
images | bmp, gif, jpg, jpeg, jpe, jif, jfif, jfi, png, wbmp, xbm, tiff |
documents | txt, pdf, rtf, doc, docx, xls, xlsx, accdb, mdb, one, pps, ppsx, ppt, pptx, pub, odt, ods, odp, odg, odf |
other | Custom file types defined in the file_types_other array |
Resources
Webhooks
Learn more about Product webhook events.
Additional Catalog endpoints
See something you can improve? Edit this file on GitHub