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

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.

  • 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

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.

  • 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

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.

  • 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    object

    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

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.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
Common Modifier properties.

Body

object | 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]

    Part of Modifier Value Response

  • display_name    string

    The name of the option shown on the storefront.

    Example: Donation

example

Response

Body

object | application/json

  • data    object

    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

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

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete a Product VideoGet all product modifiers