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

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

  • display_name
    string
    required

    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

    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

      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?