Catalog - Products

The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.

Our Catalog products endpoints let you create products, perform batch operations on existing products and work with reviews, images, and videos. Note that after a product is created initially, you can manage the nuances of its variations using the product modifier, product variant, and product variant options endpoints.

Other core product endpoints focus on bulk pricing, complex rules, custom fields, and metafields. Product variant objects also have their own metafields. For MSF-enabled stores, the product object also contains product channel assignments and category assignments; read more about products in the MSF context.

The Catalog API also contains an endpoint to get a catalog summary.

To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Resources

Webhooks

Additional Catalog endpoints

Get All Products

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

Request

Returns a list of Products. Optional filter parameters can be passed in.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
id in query - integer
Filter items by product ID.

example

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

Update Products (Batch)

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

Request

Updates products in batches. Batches are limited to 10 products.

Required Fields

id - product id is required for batch updates to products.

Read-Only Fields

id
date_created
date_modified
calculated_price
base_variant_id

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

Body

array | application/json

The model for batch updating products.

example

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

Create a Product

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

Request

Creates a Product. Only one product can be created at a time; however, you can create multiple product variants using the variants array.

Required Fields:

name
type
weight
price

Read-Only Fields

id
date_created
date_modified
calculated_price
base_variant_id

Limits

250 characters product name length.
A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB.

Usage Notes

You can create multiple product variants using the variants array.
This endpoint accepts a video array. To create a product video that accepts a video object, see Create a Product Video for information.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

Body

object | application/json

Shared Product properties used in:

POST
PUT
GET

namestring
required
A unique product name.
>= 1 characters<= 250 characters
Example: Smith Journal 13
typestring
required
The product type. One of: physical - a physical stock unit, digital - a digital download.
Allowed: physical | digital
Example: physical
skustring
A unique user-defined alphanumeric product code/stock keeping unit (SKU).
>= 0 characters<= 255 characters
Example: SM-13
descriptionstring
The product description, which can include HTML formatting.
Example: <p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>
weightnumber
required
Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store
0
Max: 9999999999
widthnumber
Width of the product, which can be used when calculating shipping costs.
0
Max: 9999999999
depthnumber
Depth of the product, which can be used when calculating shipping costs.
0
Max: 9999999999
heightnumber
Height of the product, which can be used when calculating shipping costs.
0
Max: 9999999999
pricenumber
required
The price of the product. The price should include or exclude tax, based on the store settings.
cost_pricenumber
The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
retail_pricenumber
The retail cost of the product. If entered, the retail cost price will be shown on the product page.
sale_pricenumber
If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost.
map_pricenumber
Minimum Advertised Price
tax_class_idnumber
The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
0
Max: 255
product_tax_codestring
Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerceʼs Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax providerʼs documentation.
>= 0 characters<= 255 characters
categoriesarray[number]
An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values.
0
Max: 1000
brand_idinteger
You can add a product to an existing brand during a product /PUT or /POST. Use either the brand_id or the brand_name field. The response body can include brand_id.
0
Max: 1000000000
brand_namestring
You can create the brand during a product PUT or POST request. If the brand already exists, the product /PUT or /POST request adds the product to the brand. If not, the product /PUT or /POST request creates the brand and then adds the product to the brand. Brand name is not case-sensitive; "Common Good" and "Common good" are the same. Use either the brand_id or the brand_name field. The response body does not include brand_name.
Example: Common Good
inventory_levelinteger
Current inventory level of the product. You must track inventory by product for this to take effect (see the inventory_tracking field). The Catalog API returns the inventory for only the default location.

The inventory for a product cannot exceed 2,147,483,647 in the catalog. If you exceed the limit, the store sets the inventory level to the limit.

The Catalog API handles limits in a different way than the Inventory API. For more information, see Limit handling.
0
Max: 2147483647
inventory_warning_levelinteger
Inventory warning level for the product. When the productʼs inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take any effect.
0
Max: 2147483647
inventory_trackingstring
The type of inventory tracking for the product. Values are: none - inventory levels will not be tracked; product - inventory levels will be tracked using the inventory_level and inventory_warning_level fields; variant - inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels.
Allowed: none | product | variant
fixed_cost_shipping_pricenumber
A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
is_free_shippingboolean
Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.
is_visibleboolean
Flag to determine whether the product should be displayed to customers browsing the store. If true, the product will be displayed. If false, the product will be hidden from view.
is_featuredboolean
Flag to determine whether the product should be included in the featured products panel when viewing the store.
related_productsarray[integer]
An array of IDs for the related products.
warrantystring
Warranty information displayed on the product page. Can include HTML formatting.
>= 0 characters<= 65535 characters
bin_picking_numberstring
The BIN picking number for the product.
>= 0 characters<= 255 characters
layout_filestring
The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see Custom Template Associations.
>= 0 characters<= 500 characters
upcstring
The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
>= 0 characters<= 32 characters
search_keywordsstring
A comma-separated list of keywords that can be used to locate the product when searching the store.
>= 0 characters<= 65535 characters
availability_descriptionstring
Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, such as: 'Usually ships in 24 hours.'
>= 0 characters<= 255 characters
availabilitystring
Availability of the product. (Corresponds to the productʼs Purchasability section in the control panel.) Supported values: available - the product is available for purchase; disabled - the product is listed on the storefront, but cannot be purchased; preorder - the product is listed for pre-orders.
Allowed: available | disabled | preorder
gift_wrapping_options_typestring
Type of gift-wrapping options. Values: any - allow any gift-wrapping options in the store; none - disallow gift-wrapping on the product; list – provide a list of IDs in the gift_wrapping_options_list field.

Always included in the response body; not applicable for the include_fields and exclude_fields query parameters.
Allowed: any | none | list
gift_wrapping_options_listarray[integer]
A list of gift-wrapping option IDs.

Always included in the response body; not applicable for the include_fields and exclude_fields query parameters.
sort_orderinteger
Priority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results.
Min: -2147483648
Max: 2147483647
conditionstring
The product condition. Will be shown on the product page if the is_condition_shown fieldʼs value is true. Possible values: New, Used, Refurbished.
Allowed: New | Used | Refurbished
is_condition_shownboolean
Flag used to determine whether the product condition is shown to the customer on the product page.
order_quantity_minimuminteger
The minimum quantity an order must contain, to be eligible to purchase this product.
0
Max: 1000000000
order_quantity_maximuminteger
The maximum quantity an order can contain when purchasing the product.
0
Max: 1000000000
page_titlestring
Custom title for the product page. If not defined, the product name will be used as the meta title.
>= 0 characters<= 255 characters
meta_keywordsarray[string]
Custom meta keywords for the product page. If not defined, the storeʼs default keywords will be used.
>= 0 characters<= 65535 characters
meta_descriptionstring
Custom meta description for the product page. If not defined, the storeʼs default meta description will be used.
>= 0 characters<= 65535 characters
view_countinteger
deprecated
The number of times the product has been viewed.
0
Max: 1000000000
preorder_release_datestring or null
Pre-order release date. See the availability field for details on setting a productʼs availability to accept pre-orders.
preorder_messagestring
Custom expected-date message to display on the product page. If undefined, the message defaults to the storewide setting. Can contain the %%DATE%% placeholder, which will be substituted for the release date.
>= 0 characters<= 255 characters
is_preorder_onlyboolean
If set to true then on the preorder release date the preorder status will automatically be removed. If set to false, then on the release date the preorder status will not be removed. It will need to be changed manually either in the control panel or using the API. Using the API set availability to available.
is_price_hiddenboolean
False by default, indicating that this productʼs price should be shown on the product page. If set to true, the price is hidden. (NOTE: To successfully set is_price_hidden to true, the availability value must be disabled.)
price_hidden_labelstring
By default, an empty string. If is_price_hidden is true, the value of price_hidden_label is displayed instead of the price. (NOTE: To successfully set a non-empty string value with is_price_hidden set to true, the availability value must be disabled.)
>= 0 characters<= 200 characters
custom_urlobject
The custom URL for the product on the storefront. If not provided in the POST request, the URL will be autogenerated from the product name.
open_graph_typestring
Type of product, defaults to product.
Allowed: product | album | book | drink | food | game | movie | song | tv_show
open_graph_titlestring
Title of the product, if not specified the product name will be used instead.
open_graph_descriptionstring
Description to use for the product, if not specified then the meta_description will be used instead.
open_graph_use_meta_descriptionboolean
Flag to determine if product description or open graph description is used.
open_graph_use_product_nameboolean
Flag to determine if product name or open graph name is used.
open_graph_use_imageboolean
Flag to determine if product image or open graph image is used.
gtinstring
Global Trade Item Number
mpnstring
Manufacturer Part Number
date_last_importedstring
the date when the Product had been imported
reviews_rating_suminteger
The total (cumulative) rating for the product.
Example: 3
reviews_countinteger
The number of times the product has been rated.
Example: 4
total_soldinteger
The total quantity of this product sold.
Example: 80
custom_fieldsarray[object]
200 maximum custom fields per product. 255 maximum characters per custom field. The default rate limit for this endpoint is 40 concurrent requests.
0
Max: 255
bulk_pricing_rulesarray[object]
imagesarray[]
videosarray[]
The Catalog API integrates with third-party YouTube. The YouTube Terms of Service and Google Privacy Policy apply, as indicated in our Privacy Policy and Terms of Service.
variantsarray[]

example

Response

Body

object | application/json

data
metaobject
Response metadata.

example

Delete Products

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

Request

To delete Product objects, you must include a filter. This prevents inadvertently deleting all Product objects in a store.

Note

The maximum number of products you can delete at one time is 250.

Example: To delete products with IDs 1,2 and 3, use DELETE /v3/catalog/products?id:in=1,2,3.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

example

Response

Get a Product

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

Request

Returns a single Product. Optional parameters can be passed in.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

example

Response

Body

object | application/json

data
metaobject
Response metadata.

example

Update a Product

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

Request

Updates a Product.

Limits

A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB.

Read-Only Fields

id
date_created
date_modified
calculated_price
base_variant_id

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

Body

application/json

The model for a PUT to update a product.

example

Response

Body

object | application/json

data
metaobject
Response metadata.

example

Delete a Product

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

Request

Deletes a Product.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

example

Response

Did you find what you were looking for?

Delete categories Get All Products

Catalog - Products

Resources

Webhooks

Additional Catalog endpoints

Get All Products

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Update Products (Batch)

Request

Authentication

Parameters

Body

example

Response

Body

dataarray[object]

metaobject

example

Create a Product

Request

Authentication

Parameters

Body

namestringrequired

typestringrequired

skustring

descriptionstring

weightnumberrequired

widthnumber

depthnumber

heightnumber

pricenumberrequired

cost_pricenumber

retail_pricenumber

sale_pricenumber

map_pricenumber

tax_class_idnumber

product_tax_codestring

categoriesarray[number]

brand_idinteger

brand_namestring

inventory_levelinteger

inventory_warning_levelinteger

inventory_trackingstring

fixed_cost_shipping_pricenumber

is_free_shippingboolean

is_visibleboolean

is_featuredboolean

related_productsarray[integer]

warrantystring

bin_picking_numberstring

layout_filestring

upcstring

search_keywordsstring

availability_descriptionstring

availabilitystring

gift_wrapping_options_typestring

gift_wrapping_options_listarray[integer]

sort_orderinteger

conditionstring

is_condition_shownboolean

order_quantity_minimuminteger

order_quantity_maximuminteger

page_titlestring

meta_keywordsarray[string]

meta_descriptionstring

view_countintegerdeprecated

preorder_release_datestring or null

preorder_messagestring

is_preorder_onlyboolean

is_price_hiddenboolean

price_hidden_labelstring

custom_urlobject

namestring
required

typestring
required

weightnumber
required

pricenumber
required

view_countinteger
deprecated