Docs
Store operations
Catalog and inventory
Products overview

Catalog Overview

The Catalog refers to a store's collection of physical and digital products. The Catalog includes all the information about a product such as MPN, warranty, price, and images.

OAuth scopes

UI NamePermissionParameter
Productsmodifystore_v2_products
Productsread-onlystore_v2_products_read_only

For more information on OAuth Scopes and authentication, see our Guide to API Accounts.

Products overview

Products are the primary catalog entity, and the primary function of the ecommerce platform is to sell products on the storefront and other channels.

Products can be physical or digital:

  • Physical - Exist in a physical form, have a weight, and are sold by merchants to ship to customers.

  • Digital - Non-physical products, including downloadable files (for example, computer software, ebooks, or music) and services (for example, haircuts, consulting, or lawn care).

Only one product can be created at a time.

Creating a product

Below is an example POST request for creating a simple product without variant options or modifiers.

Example request: Create a product
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "name": "BigCommerce Coffee Mug",
  "price": "10.00",
  "categories": [
    23,
    21
  ],
  "weight": 4,
  "type": "physical"
}

Creating products with variant options

To create a complex product with variant options selectable by shoppers, include a variants array in the request body.

Example request: Create a product
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "name": "BigCommerce Coffee Mug",
  "price": "10.00",
  "categories": [
    23,
    21
  ],
  "weight": 4,
  "type": "physical",
  "variants": [
    {
      "sku": "SKU-BLU",
      "option_values": [
        {
          "option_display_name": "Mug Color",
          "label": "Blue"
        }
      ]
    },
    {
      "sku": "SKU-GRAY",
      "option_values": [
        {
          "option_display_name": "Mug Color",
          "label": "Gray"
        }
      ]
    }
  ]
}

When you create options via /products, display_type defaults to a radio button (displayed as selectable boxes in some themes).

Creating digital products

To create a digital product (like an ebook), set type to digital.

Example request: Create a product
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "name": "ebook: A Guide to Coffee",
  "price": "10.00",
  "categories": [
    23,
    21
  ],
  "type": "digital",
  "images": [
    {
      "is_thumbnail": true,
      "image_url": "{{image_url}}"
    }
  ]
}

Files can only be added to digital products via control panel or WebDav (opens in a new tab) -- attaching via the API is not supported. You can also set additional settings such as file description and maximum downloads in the control panel.

Adding product images

To add an image to a product, send a POST request to /v3/catalog/products/{{product_id}}/images.

Example request: Create a product image
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/images
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "is_thumbnail": true,
  "sort_order": 1,
  "description": "Yellow Large Bath Towel",
  "image_url": "{{image_url}}"
}
  • If using image_file, set Content-Type header to multipart/form-data -- otherwise, you will be unable to add subsequent requests.
  • Set is_thumbmail to true to set the image as the thumbnail used on product listing pages.
  • A product can have only one thumbnail image at a time.
  • If only one image is on the product, it becomes both the thumbnail and the main product image.
  • You can also add images to variants.

Adding product videos

To add a video hosted on YouTube as a product video, send a POST request to /v3/catalog/products/{{product_id}}/videos.

Example request: Create a product video
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/videos
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "title": "BigCommerce Mug Video",
  "description": "Video Describing the Mug",
  "sort_order": 1,
  "type": "youtube",
  "video_id": "R12345677"
}
  • A product can have more than one video.
  • You must host product videos on YouTube.
  • video_id corresponds to the v parameter in the URL (Ex: https://www.youtube.com/watch?v=R12345677).

Adding custom fields

To add custom fields to a product, send a POST request to /v3/catalog/products/{{product_id}}/custom-fields.

Example request: Create a custom fields
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/custom-fields
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "name": "Release Year",
  "value": "2018"
}

Custom field values are limited to 250 characters. For additional information on custom fields and their use cases, see Custom Fields (opens in a new tab).

Adding bulk pricing rules

To add bulk quantity-based pricing to products, send a PUT request to /v3/catalog/products/{{product_id}}/bulk-pricing-rules.

Example request: Create a bulk pricing rule
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/bulk-pricing-rules
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "bulk_pricing_rules": [
    {
      "quantity_min": 10,
      "quantity_max": 15,
      "type": "price",
      "amount": 3
    },
    {
      "quantity_min": 16,
      "quantity_max": 25,
      "type": "price",
      "amount": 5
    }
  ]
}

For general information and use cases for product bulk pricing, see Bulk Pricing (opens in a new tab).

Pricing precision

BigCommerce pricing is precise up to 4 decimal places. For example:

  • "$ 10.99999 rounds up to $ 11
  • "$ 10.99994 rounds down to $ 10.9999

Currency display settings allow for more than four decimal places. In such cases, the additional decimal places will display as 0s.

Adding product metafields

Metafields are key-value pairs intended for programmatically storing data against a product or other entity. Data stored in metafields does not appear in the storefront or the control panel. Data not appearing in the storefront or control panel is useful when information needs to be passed back and forth between an app and BigCommerce.

To add metafields to a product, send a POST request to /v3/catalog/products/{{product_id}}/metafields.

Example request: Create a product metafield
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/metafields
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "permission_set": "read",
  "namespace": "Location",
  "key": "bin_number",
  "value": "#4456",
  "description": "location of the product",
  "resource_type": "product",
  "resource_id": 131
}

Adding product reviews

To add product reviews to a product, send a POST request to /v3/catalog/products/{{product_id}}/reviews.

Example request: Create a product review
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/reviews
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "title": "Great Coffee Mug",
  "text": "This coffee mug kept my liquids hot for several hours.",
  "status": "pending",
  "rating": 5,
  "email": "testing@bigcommerce.com",
  "name": "BigCommerce",
  "date_reviewed": "2018-07-20T17:45:13+00:00"
}

You cannot create reviews in the control panel.

Variant options

Variant options are any choices that the shopper needs to make that will result in selecting a variant. Color and size are typical examples of variant options. A t-shirt can have different combinations of sizes and colors.

Example:

  • Color is a variant option; red, orange, and green are variant option values.
  • Size is a variant option; small, medium, and large are variant option values.

This example results in selecting a combination of small and red on the storefront and correlates to a product variation, also called a SKU.

Variant options:

  • Require the shopper to select a value
  • Only support “multiple choice” option types
  • Rectangle
  • Radio button
  • Color swatch
  • Product pick list
  • Product pick list with images
  • Will automatically generate variants when created in the control panel
  • Are auto-generated from variants when you create a product with variants using the Create a product endpoint

Variant options example

ProductVariant option
T-ShirtBlue
-
Small
Medium
Large
BackpackBlack
Yellow
-
2L
3L
8L

Options created on V2 and V3

  • If a product has variant options created using the V2 API, you cannot add additional variant options using the V3 API.
  • SKUs in V2 map to variants in V3.
  • Base variants are not SKUs in V2.

Create a variant option

Creating a variant option does not automatically create SKUs or build out variants. You can build out SKUs later using the Create product variants endpoint.

Create variant options

The following request will create options that will show on the storefront as choices selected by the customer. In a separate request, you could build out SKUs based on these variant option values or a combination of variant option values. You can use a similar request to add new choices to an existing variant.

Example request: Create Size Variant Option
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/options
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "product_id": 134,
  "name": "Size Rectangle",
  "display_name": "Size",
  "type": "rectangles",
  "option_values": [
    {
      "label": "S",
      "sort_order": 0,
      "is_default": false
    },
    {
      "label": "M",
      "sort_order": 1,
      "is_default": true
    },
    {
      "label": "L",
      "sort_order": 2,
      "is_default": false
    }
  ]
}

Variants

Variants represent an item as it sits on the shelf in the warehouse or a particular saleable product. A product might be a t-shirt, while the variant would be “a small, red t-shirt.” Shoppers select variants on the storefront via product options. In the case where a product is simple, meaning it does not have any options, the product is its own variant - called a base variant. Everything you can buy should be a variant.

  • Options build out variants.
  • Variants are usually what you track inventory against.
  • Can have their own price, weight, dimensions, image, etc. - or they can inherit these values from the product if you have not specified them.
  • Must have a SKU code (unless they are a base variant).
  • In non-base variants, variants will relate to a particular combination of variant option values - such as “small” and “red”.
⚠️

V2 SKU rules will override variant pricing

Creating SKU rules via the V2 API or via CSV import will alter or override any variant price or sale price added to a product via the control panel, V3 API, or Price Lists UI.

Variant examples:

ProductVariant optionVariant
T-ShirtBlue
-
Small
Medium
Large
SM-BLU
SM-MED
SM-LARG
BackpackBlack
Yellow
-
2L
3L
8L
BLACK-2L
BLACK-3L
BLACK 8L
-
YELLOW-2L
YELLOW-3L
YELLOW-8L

Creating variants

You can create variants in two ways:

The example below will go over using existing variant options to create the variants.

To fetch variant information, send a GET request to /v3/catalog/products/{{product_id}}/options.

Example request: Get product variant options
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/options
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "data": [
    {
      "id": 193,
      ...
      "option_values": [
        {
          "id": 163,
          "label": "S",
          "sort_order": 0,
          "value_data": null,
          "is_default": false
        },
        ...
      ],
      "config": []
    },
    {
      "id": 194,
      ...
      "option_values": [
        {
          "id": 166,
          "label": "Blue",
          "sort_order": 1,
          "value_data": {
            "colors": [
              "#123C91"
            ]
          },
          ...
      ],
      "config": []
    }
  ],
  "meta": {
    ...
    }
  }
}

In the above response, there are two variant options of size and color with three values each.

To combine the variant option values into variants and build out SKUs use the following endpoint:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/variants

  • If you want only some option combinations to have a variant, do not edit the variant options in the control panel, as that will cause the store to autogenerate all missing variant SKUs.
  • You can create only one variant option at a time; individual variant options will contain an array of multiple values.
  • To use a variant array and create variants in the same call as the base product, use the /catalog/product endpoint during product creation.

The option_values array combines the options small and blue to create the SKU SMALL-BLUE. The ID in the option_values array is the ID from the variant option response option_values > id. The option_id is the ID of the option.

{
  "id": 193, //option_id
  "product_id": 134,
  "name": "Size1533313432-134",
  "display_name": "Size",
  "type": "rectangles",
  "sort_order": 0,
  "option_values": [
    {
        "id": 163, //id
        "label": "S",
        "sort_order": 0,
        "value_data": null,
        "is_default": false
    },
    ...
  ]
}

Create a variant using the product endpoint

The following example creates a base product, variant options, and variants in a single call to the Products endpoint. Use this method to create a product and variants in a single call without creating variant options first (option display will default to rectangles).

Example request: Create a variant using the product endpoint
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
 
{
  "name": "BigCommerce Coffee Mug",
  "price": "10.00",
  "categories": [
    23,
    21
  ],
  "weight": 4,
  "type": "physical",
  "variants": [
    {
      "sku": "SKU-BLU",
      "option_values": [
        {
          "option_display_name": "Mug Color",
          "label": "Blue"
        }
      ]
    },
    {
      "sku": "SKU-GRAY",
      "option_values": [
        {
          "option_display_name": "Mug Color",
          "label": "Gray"
        }
      ]
    }
  ]
}

Supported types

Swatch, radio button, rectangle, dropdown, product list, and product list with images.

Modifier options

Modifier options are any choices that the shopper can make to change how the merchant fulfills the product. Examples include:

  • A checkbox to add shipping insurance
  • Text to be engraved on the product
  • A selected color for an unfinished product before it’s shipped

Critically, the modifier will not change the SKU/variant fulfilled, and you cannot track inventory against combinations of modifier values. Modifiers typically would not change which product is “picked off the shelf” in the warehouse, but they change what happens to that product before sending it to the shopper, or how a merchant can send it.

Modifier options:

  • May be required or non-required
  • Support all option types
  • Cannot be used as part of a variant

You can add an adjuster to a modifier option to change things, such as increasing the price, changing the weight, or shipping rules. You cannot apply adjusters to all modifier types.

Modifier options example

ProductVariant optionVariantModifier
T-ShirtBlue
-
Small
Medium
Large
BLU
BLU-MED
BLU-LARG
Checkbox
Donate to Charity
BackpackBlack
Yellow
-
2L
3L
8L
BLACK-2L
BLACK-3L
BLACK 8L
-
YELLOW-2L
YELLOW-3L
YELLOW-8L
Text Field
Add Embroidery

Modifiers that support adjusters

Swatch, radio button, rectangle list, drop-down, product list, and product list with images.

Add a modifier with price adjuster to an existing product

The following example shows how to add a modifier and a checkbox with a price adjuster to increase the product's price by five dollars.

Creating a checkbox with an adjuster requires two separate calls: one to create the checkbox and another one to add the adjuster. You can define adjusters within the option_values array, but option_values are not allowed in the request to create a checkbox modifier because creating a checkbox automatically generates two mandatory option values: Yes and No. Once you have created the checkbox and its option values, you can update the modifier to add an adjuster.

Modifiers that require a second step to add an adjuster

Swatch, radio button, drop-down, rectangle list, product list, product list with images, and checkbox.

To create a modifier, send a POST request to /v3/catalog/products/{{product_id}}/modifiers.

Example request: Create a product modifier
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/modifiers
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "type": "checkbox",
  "required": false,
  "config": {
    "default_value": "Yes",
    "checked_by_default": false,
    "checkbox_label": "Check for Donation"
  },
  "display_name": "Add a $5 Donation"
}

Since this is a checkbox with two states, you create two option values. The default adjuster_value is null.

To update the modifier value, send a PUT request to /v3/catalog/products/{{product_id}}/modifiers/{{modifier_id}}/values/{value_id}.

Example request: Update a product modifier value
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/modifiers/{{modifier_id}}/values/{value_id}
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "is_default": false,
  "adjusters": {
    "price": {
      "adjuster": "relative",
      "adjuster_value": 5
    }
  }
}

Troubleshooting: 422 Errors

{
    "status": 422,
    "title": "The product is currently associated with an option set, please remove it before editing an option or modifier.",
    "type": "https://developer.bigcommerce.com/docs/start/about/status-codes",
    "errors": {
        "product_id": "The product is currently associated with an option set, please remove it before editing an option or modifier."
    }
}

To fix this error:

  • Modify the products using the V2 API.
  • Remove the option set using the V2 API or the control panel, then remake the variants and modifiers using V3.

Complex rules

Complex rules allow merchants to set up conditions and actions based on shopper option selections on the storefront. You can use them to vary the following based on the shopper's option selections:

  • Price
  • Weight
  • Image
  • Purchasability

Adjustments made by complex rules are displayed to shoppers in real-time on the storefront.

For most merchant use cases, best practice will be to either assign values (such as a price) directly to a variant or use adjusters on the modifier option itself. However, complex rules exist for rare cases where a rule condition is too complex to express in those forms easily.

Use complex rules when an adjustment should be triggered by:

  • The selection of values across multiple modifier options.
  • The combination of a particular variant/SKU and a modifier option value.

Complex rules example

ProductVariant optionVariantModifierComplex rule
T-ShirtBlue
-
Small
Medium
Large
SM-BLU
SM-MED
SM-LARG
Checkbox
Donate to Charity
Checkbox
Donate to Charity.
Add $5
BackpackBlack
Yellow
-
2L
3L
8L
BLACK-2L
BLACK-3L
BLACK 8L
-
YELLOW-2L
YELLOW-3L
YELLOW-8L
Text Field
Add Embroidery
N/A

Creating complex rules based on modifiers

Complex rules must have a combination of two or more modifiers, such as two checkboxes. The following example will add $10 to the product price when you check both boxes.

Example request: Create a complex rule
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/complex-rules
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "product_id": 1200,
  "enabled": true,
  "price_adjuster": {
    "adjuster_value": 10
  },
  "conditions": [
    {
      "modifier_id": 506,
      "modifier_value_id": 852
    },
    {
      "modifier_id": 507,
      "modifier_value_id": 854
    }
  ]
}

Troubleshooting: 422 Errors

Complex rules must consist of multiple conditions that trigger the rule adjustment. If multiple conditions are not specified, the request will return a 422 error.

{
    "status": 422,
    "title": "The rule must contain multiple modifier conditions with unique modifier ids or a variant condition and modifier condition",
    "type": "https://developer.bigcommerce.com/docs/start/about/status-codes"
}

Creating brands

To create a Brand, send a POST request to /v3/catalog/brands.

Example request: Create a brand
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/brands
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "name": "BigCommerce",
  "page_title": "BigCommerce",
  "meta_keywords": [
    "ecommerce",
    "best in class",
    "grow your business"
  ],
  "image_url": "{{image_url}}"
}

For general information on brands and their use cases, see Managing Brands (opens in a new tab).

Categories

Categories are a hierarchy of products available on the store, presented in a tree structure. A store's category structure determines the primary menu structure of most storefront themes directly tied to it.

BigCommerce's V3 REST API does not require products to be associated with a category during creation. You can add new products to a catalog without a category, which can be assigned later if desired. A store's category can contain multiple products or no products at all and still be valid.

You can associate products with multiple categories. A product associated with categories does not currently have any priority or weighted order (there's no “primary category”). The absence of priority or weighted order makes it difficult to integrate with some external systems that might wish to use a product's categories to map to a category structure.

Example request: Create a category
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories
 
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "parent_id": 18,
  "name": "Shoes",
  "description": "Shoes Available for purchase",
  "sort_order": 1,
  "page_title": "Shoes",
  "is_visible": true
}

Category tree

Category Tree returns a simple view of the parent > child relationship of all categories in the store. You can use this endpoint to fetch the categories if building out a custom navigation for a store.

Example request: Get a category tree
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/trees/{{TREE_ID}}/categories
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

Product Sort Order

Product Sort Order allows you to manage the sort order of products displayed on any given category page. Products assigned to multiple storefront categories can have different sort order values per category.

Product sorting on a storefront

The Catalog API supports two manually managed methods of product sorting: on a category level and a product level. If a user combines both sorting methods on a storefront, products with sort order values on a category level take priority. If there is no sort order value on a category level, the Catalog API sorts products by values on a product level.

Product sorting methods:

  1. Manually specified sort order on a category level.
  2. Manually specified sort order on a product level. 0 by default.

Products with the same sort order value either on a category or a product level are sorted by product id as a second criterion.

Related resources

Endpoints

Webhooks

Did you find what you were looking for?