Docs
Catalog API
Product modifiers

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.

Resources

Webhooks

Learn more about Product webhook events.

Additional Catalog endpoints

Get all product modifiers

GET /catalog/products/{product_id}/modifiers

Request

Returns a list of all product modifiers. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • include_fields in query - array

    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

    Type: array[string]

  • exclude_fields in query - array

    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

    Type: array[string]

  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query with default of 50 - integer

    Controls the number of items per page in a limited (paginated) list of products.

example

Response

Body

object | application/json

Modifier Collection Response return for /GET All Modifiers.

  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example

Create a product modifier

POST /catalog/products/{product_id}/modifiers

Request

Creates a product modifier.

Required Fields

  • required
  • display_name
  • type

Read-Only Fields

  • id

Notes It takes two separate requests to create a new checkbox modifier with option values. Perform a request to create a modifier, then perform a second request to update option values.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

object | application/json

Common Modifier properties.

  • type
    string
    required

    BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

    Allowed: date | checkbox | file | text | multi_line_text | numbers_only_text | radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • required
    boolean
    required

    Whether or not this modifier is required at checkout. Required in a /POST.

  • sort_order
    integer

    The order the modifiers display on the product detail page.

  • config
    object

    The values for option config can vary based on the Modifier created.

  • option_values
    array[object]

  • display_name
    string
    required

    The name of the option shown on the storefront.

example

Response

Body

object | application/json
  • data
    object

  • meta
    object

    Response metadata.

example

Get a product modifier

GET /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Returns a single product modifier. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • include_fields in query - array

    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

    Type: array[string]

  • exclude_fields in query - array

    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

    Type: array[string]

example

Response

Body

object | application/json
  • data

    Product modifier

  • meta
    object

    Response metadata.

example

Update a product modifier

PUT /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Updates a product modifier.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

application/json

The model for a PUT to update a modifier on a product.

  • type
    string
    required

    BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

    Allowed: date | checkbox | file | text | multi_line_text | numbers_only_text | radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • required
    boolean
    required

    Whether or not this modifier is required at checkout. Required in a /POST.

  • sort_order
    integer

    The order the modifiers display on the product detail page.

  • config
    object

    The values for option config can vary based on the Modifier created.

  • option_values
    array[object]

  • display_name
    string

    The name of the option shown on the storefront.

    Example: Donation

  • type
    string
    required

    BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

    Allowed: date | checkbox | file | text | multi_line_text | numbers_only_text | radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • required
    boolean
    required

    Whether or not this modifier is required at checkout. Required in a /POST.

  • sort_order
    integer

    The order the modifiers display on the product detail page.

  • config
    object

    The values for option config can vary based on the Modifier created.

  • option_values
    array[object]

  • display_name
    string

    The name of the option shown on the storefront.

    Example: Donation

example

Response

Body

object | application/json
  • data

    Product modifier

  • meta
    object

    Response metadata.

example

Delete a product modifier

DELETE /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Deletes a product modifier.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • product_id in path - integer
    required

    The ID of the product to which the resource belongs.

  • modifier_id in path - integer
    required

    The ID of the product modifier.

example

Response

Did you find what you were looking for?