> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # 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](/developer/docs/admin/catalog-and-inventory). 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** — can include a `colors` array with up to three hexidecimal color keys or an `image_url` field with a full image URL path including procotol for a custom pattern * **product list/product list with images** — uses the `product_id` field to identify the product in the list * **checkbox** — uses the boolean `checked_value` field to indicate whether the option value is the "checked" state. | swatch, product list, product list with images, checkbox | | `adjusters.price` | Price adjustment for [complex rules](/developer/docs/admin/catalog-and-inventory#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](/developer/docs/admin/catalog-and-inventory#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-8601 ATOM 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-8601 ATOM date: the earliest date allowed to be entered on the date option | | | `date_latest_value` | ISO-8601 ATOM 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](#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](/developer/docs/integrations/webhooks/event-reference#products). ### Additional Catalog endpoints * [Brands](/developer/api-reference/rest/admin/catalog/brands) * [Categories](/developer/api-reference/rest/admin/catalog/categories) * [Category trees](/developer/api-reference/rest/admin/catalog/category-trees) * [Products](/developer/api-reference/rest/admin/catalog/products) * [Product variants](/developer/api-reference/rest/admin/catalog/product-variants) * [Product variant options](/developer/api-reference/rest/admin/catalog/product-variant-options)