BigCommerce
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 a color selection for an unfinished product.

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

  • page in query - integer

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

  • limit in query - integer

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

  • include_fields in query - string

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

  • exclude_fields in query - string

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

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

application/json

The model for a POST to create 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 modifer is required or not 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: Donation

    example

    Response

    Body

    object | application/json

    • data      object

      Product Modifier

    • meta      object

      Response metadata.

    example

    Get a 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
    • 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 Modifier.

    • include_fields in query - string

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

    • exclude_fields in query - string

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

    example

    Response

    Body

    object | application/json

    • data

      Product Modifier

    • meta      object

      Response metadata.

    example

    Update a 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 or not 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        object

        Product Modifier

      • meta        object

        Response metadata.

      example

      Delete a 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 Modifier.

      example

      Response

      Delete a Product VideoGet All Product Modifiers