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/productsRequest
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- id in query - integer
Filter items by product ID.
- id:in in query - arrayPass a comma-separated list to filter by one or more product IDs.Type: array[integer]
- channel_id:in in query - arrayPass a comma-separated list to filter by one or more channel IDs.Type: array[integer]
- id:not_in in query - arrayPass a comma-separated list to exclude one or more product IDs.Type: array[integer]
- include in query - array
A comma-separated list of sub-resources to return with a product object. When you specify
options
ormodifiers
, results are limited to 10 per page.Type: array[string]Allowed: bulk_pricing_rules | reviews | modifiers | options | parent_relations | custom_fields | channels | videos
- include_fields in query - arrayFields to include, in a comma-separated list. The ID and the specified fields will be returned.Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
- exclude_fields in query - arrayFields 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.
- direction in query - string
Sort direction. Acceptable values are:
asc
,desc
.Allowed: asc | desc
- sort in query - string
Field name to sort by. Note: Since ID increments when new products are added, you can use the ID value to sort by product create date.
Allowed: id | name | sku | price | date_modified | date_last_imported | inventory_level | is_visible | total_sold | calculated_price
- categories:in in query - arrayA comma-separated list of category IDs. Returns a list of products that are in all the categories specified.Type: array[integer]
- id:min in query - integer
- id:max in query - integer
- id:greater in query - integer
- id:less in query - integer
- name in query - string
Filter items by name.
- mpn in query - string
Filter items by Manufacturer Part Number (MPN).
- upc in query - string
Filter items by UPC.
- price in query - number
Filter items by price.
- weight in query - number
Filter items by weight.
- condition in query - string
Filter items by condition.
Allowed: new | used | refurbished
- brand_id in query - integer
Filter items by brand ID.
- date_modified in query - stringFilter items by
date_modified
. - date_modified:max in query - stringFilter items by
date_modified
. If thedate modified:max
does not include hours, minutes and seconds, the API automatically adds the current time of the request to the date. For example,date_modified:max=2025-01-15
ordate_modified:max=2025-01-15T00:03:17Z
. - date_modified:min in query - stringFilter items by
date_modified
. If thedate modified:min
does not include hours, minutes and seconds, the API automatically adds the current time of the request to the date. For example,date_modified:min=2025-01-15
ordate_modified:min=2025-01-15T00:03:17Z
. - date_last_imported in query - stringFilter items by date_last_imported.
- date_last_imported:not in query - stringFilter products by specifying a date they were NOT last imported. For example,
date_last_imported:not=2015-08-21T22%3A53%3A23%2B00%3A00
. - date_last_imported:max in query - stringFilter items by date_last_imported. For example,
date_last_imported:max=2015-08-21T22%3A53%3A23%2B00%3A00
. - date_last_imported:min in query - stringFilter items by date_last_imported. For example,
date_last_imported:min=2015-08-21T22%3A53%3A23%2B00%3A00
. - is_visible in query - booleanFilter items based on whether the product is currently visible on the storefront.
- is_featured in query - integerFilter items by is_featured.
1
for true,0
for false.Allowed: 1 | 0
- is_free_shipping in query - integerFilter items by is_free_shipping.
1
for true,0
for false. - inventory_level in query - integer
Filter items by inventory_level.
- inventory_level:in in query - arrayA comma-separated list of inventory levels. Returns a list of all products that have any of the listed inventory amounts.Type: array[integer]
- inventory_level:not_in in query - arrayA comma-separated list of inventory levels. Returns a list of all products that have inventory amounts other than those specified.Type: array[integer]
- inventory_level:min in query - integer
- inventory_level:max in query - integer
- inventory_level:greater in query - integer
- inventory_level:less in query - integer
- inventory_low in query - integer
Filter items by inventory_low. Values: 1, 0.
- out_of_stock in query - integer
Filter items by out_of_stock. To enable the filter, pass
out_of_stock
=1
. - total_sold in query - integer
Filter items by total_sold.
- type in query - stringFilter items by type.
Allowed: digital | physical
- categories in query - integer
Filter items by categories. If a product is in more than one category, using this query will not return the product. Instead use
categories:in=12
. - keyword in query - stringFilter items by keywords found in the
name
,description
, orsku
fields, or in the brand name. - keyword_context in query - stringSet context used by the search algorithm to return results targeted towards the specified group. Use
merchant
to help merchants search their own catalog. Useshopper
to return shopper-facing search results.Allowed: shopper | merchant
- availability in query - string
Filter items by availability. Values are: available, disabled, preorder.
Allowed: available | disabled | preorder
- sku in query - stringFilter items by main SKU. To filter by variant SKU, see Get all variants.
- sku:in in query - arrayA comma-separated list of SKUs. Returns a list of products with those SKUs.Type: array[string]
example
Response
Body
dataarray[object]
example
Update Products (Batch)
PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/productsRequest
Updates products in batches. Batches are limited to 10 products.
Required Fields
id
- product
id
is required for batch updates to products.
- product
Read-Only Fields
id
date_created
date_modified
calculated_price
base_variant_id
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
- include_fields in query - arrayFields to include, in a comma-separated list. The ID and the specified fields will be returned.Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
Body
idinteger
requiredread-onlyUnique ID of the Product. Read-Only.namestring
>= 1 characters<= 250 charactersA unique product name.
Example: Smith Journal 13typestring
The product type. One of:
physical
- a physical stock unit,digital
- a digital download.Allowed: physical | digital
Example: physicalskustring
>= 0 characters<= 255 charactersA unique user-defined alphanumeric product code/stock keeping unit (SKU). The SKU is always unique regardless of the letter case for both products and variants.
Example: SM-13descriptionstring
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
Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store.
Min: 0Max: 9999999999widthnumber
Width of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999depthnumber
Depth of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999heightnumber
Height of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999pricenumber
The price of the product. The price should include or exclude tax, based on the store settings.
Min: 0cost_pricenumber
The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
Min: 0retail_pricenumber
The retail cost of the product. If entered, the retail cost price will be shown on the product page.
Min: 0sale_pricenumber
If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost.
Min: 0map_pricenumber
Minimum Advertised Pricetax_class_idnumber
The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
Min: 0Max: 255product_tax_codestring
>= 0 characters<= 255 charactersTax 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.
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.
Min: 0Max: 1000brand_idinteger
You can add a product to an existing brand during a product /PUT or /POST. Use either the
brand_id
or thebrand_name
field. The response body can includebrand_id
.Min: 0Max: 1000000000brand_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 thebrand_id
or thebrand_name
field. The response body does not includebrand_name
.Example: Common Goodinventory_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.
Min: 0Max: 2147483647inventory_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.Min: 0Max: 2147483647inventory_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 theinventory_level
andinventory_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.
Min: 0is_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. Iffalse
, 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.warrantystring
>= 0 characters<= 65535 charactersWarranty information displayed on the product page. Can include HTML formatting.
bin_picking_numberstring
>= 0 characters<= 255 charactersThe BIN picking number for the product.
layout_filestring
>= 0 characters<= 500 charactersThe 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.
upcstring
>= 0 characters<= 14 charactersThe product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywordsstring
>= 0 characters<= 65535 charactersA comma-separated list of keywords that can be used to locate the product when searching the store.
availability_descriptionstring
>= 0 characters<= 255 charactersAvailability 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.'
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
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: -2147483648Max: 2147483647conditionstring
The product condition. Will be shown on the product page if the
is_condition_shown
fieldʼs value istrue
. 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.
Min: 0Max: 1000000000order_quantity_maximuminteger
The maximum quantity an order can contain when purchasing the product.
Min: 0Max: 1000000000page_titlestring
>= 0 characters<= 255 charactersCustom title for the product page. If not defined, the product name will be used as the meta title.
view_countinteger
deprecatedThe number of times the product has been viewed.
Min: 0Max: 1000000000preorder_release_datestring or null
Pre-order release date. See the
availability
field for details on setting a productʼs availability to accept pre-orders.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
toavailable
.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 setis_price_hidden
totrue
, theavailability
value must bedisabled
.)price_hidden_labelstring
>= 0 characters<= 200 charactersBy default, an empty string. If
is_price_hidden
istrue
, the value ofprice_hidden_label
is displayed instead of the price. (NOTE: To successfully set a non-empty string value withis_price_hidden
set totrue
, theavailability
value must bedisabled
.)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_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>= 0 characters<= 14 charactersmpnstring
Manufacturer Part Numberdate_last_importedstring
the date when the Product had been importedreviews_countinteger
The number of times the product has been rated.
Example: 4total_soldinteger
The total quantity of this product sold.
Example: 80custom_fieldsarray[object]
200 maximum custom fields per product. 255 maximum characters per custom field.Min: 0Max: 255bulk_pricing_rulesarray[object]
imagesarray[object]
videosarray[object]
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.
example
Response
Body
dataarray[object]
example
Create a Product
POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/productsRequest
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
categories
(required when you enable the V2 product experience in the control panel)
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 avideo
object, see Create a Product Video for information.
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
- include_fields in query - arrayFields to include, in a comma-separated list. The ID and the specified fields will be returned.Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
Body
Product
properties used in:
POST
namestring
required>= 1 characters<= 250 charactersA unique product name.
Example: Smith Journal 13typestring
requiredThe product type. One of:
physical
- a physical stock unit,digital
- a digital download.Allowed: physical | digital
Example: physicalskustring
>= 0 characters<= 255 charactersA unique user-defined alphanumeric product code/stock keeping unit (SKU). The SKU is always unique regardless of the letter case for both products and variants.
Example: SM-13descriptionstring
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
requiredWeight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store
Min: 0Max: 9999999999widthnumber
Width of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999depthnumber
Depth of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999heightnumber
Height of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999pricenumber
requiredThe price of the product. The price should include or exclude tax, based on the store settings.
Min: 0cost_pricenumber
The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
Min: 0retail_pricenumber
The retail cost of the product. If entered, the retail cost price will be shown on the product page.
Min: 0sale_pricenumber
If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost.
Min: 0map_pricenumber
Minimum Advertised Pricetax_class_idnumber
The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
Min: 0Max: 255product_tax_codestring
>= 0 characters<= 255 charactersTax 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.
categoriesarray[number]
An array of IDs for the categories to which this product belongs. You will overwrite all product categories when updating a product and supplying an array of categories. The limit is 1,000 ID values. When you enable the catalog V2 product experience in the control panel, you must include the categories array in the request body.
Min: 0Max: 1000brand_idinteger
You can add a product to an existing brand during a product /PUT or /POST. Use either the
brand_id
or thebrand_name
field. The response body can includebrand_id
.Min: 0Max: 1000000000brand_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 thebrand_id
or thebrand_name
field. The response body does not includebrand_name
.Example: Common Goodinventory_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.
Min: 0Max: 2147483647inventory_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.Min: 0Max: 2147483647inventory_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 theinventory_level
andinventory_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.
Min: 0is_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. Iffalse
, 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.warrantystring
>= 0 characters<= 65535 charactersWarranty information displayed on the product page. Can include HTML formatting.
bin_picking_numberstring
>= 0 characters<= 255 charactersThe BIN picking number for the product.
layout_filestring
>= 0 characters<= 500 charactersThe 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.
upcstring
>= 0 characters<= 14 charactersThe product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywordsstring
>= 0 characters<= 65535 charactersA comma-separated list of keywords that can be used to locate the product when searching the store.
availability_descriptionstring
>= 0 characters<= 255 charactersAvailability 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.'
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
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: -2147483648Max: 2147483647conditionstring
The product condition. Will be shown on the product page if the
is_condition_shown
fieldʼs value istrue
. 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.
Min: 0Max: 1000000000order_quantity_maximuminteger
The maximum quantity an order can contain when purchasing the product.
Min: 0Max: 1000000000page_titlestring
>= 0 characters<= 255 charactersCustom title for the product page. If not defined, the product name will be used as the meta title.
view_countinteger
deprecatedThe number of times the product has been viewed.
Min: 0Max: 1000000000preorder_release_datestring or null
Pre-order release date. See the
availability
field for details on setting a productʼs availability to accept pre-orders.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
toavailable
.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 setis_price_hidden
totrue
, theavailability
value must bedisabled
.)price_hidden_labelstring
>= 0 characters<= 200 charactersBy default, an empty string. If
is_price_hidden
istrue
, the value ofprice_hidden_label
is displayed instead of the price. (NOTE: To successfully set a non-empty string value withis_price_hidden
set totrue
, theavailability
value must bedisabled
.)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_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>= 0 characters<= 14 charactersmpnstring
Manufacturer Part Numberdate_last_importedstring
the date when the Product had been importedreviews_countinteger
The number of times the product has been rated.
Example: 4total_soldinteger
The total quantity of this product sold.
Example: 80custom_fieldsarray[object]
200 maximum custom fields per product. 255 maximum characters per custom field.Min: 0Max: 255bulk_pricing_rulesarray[object]
imagesarray[object]
videosarray[object]
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[object]
example
Response
Body
dataobject
Base Product response
example
Delete Products
DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/productsRequest
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- name in query - string
Filter items by name.
- sku in query - stringFilter items by main SKU. To filter by variant SKU, see Get all variants.
- price in query - number
Filter items by price.
- weight in query - number
Filter items by weight.
- condition in query - string
Filter items by condition.
Allowed: new | used | refurbished
- brand_id in query - integer
Filter items by brand ID.
- date_modified in query - stringFilter items by
date_modified
. - date_last_imported in query - stringFilter items by date_last_imported.
- is_visible in query - booleanFilter items based on whether the product is currently visible on the storefront.
- is_featured in query - integerFilter items by is_featured.
1
for true,0
for false.Allowed: 1 | 0
- id:in in query - arrayPass a comma-separated list to filter by one or more product IDs.Type: array[integer]
- inventory_level in query - integer
Filter items by inventory_level.
- total_sold in query - integer
Filter items by total_sold.
- type in query - stringFilter items by type.
Allowed: digital | physical
- categories in query - integer
Filter items by categories. If a product is in more than one category, using this query will not return the product. Instead use
categories:in=12
. - keyword in query - stringFilter items by keywords found in the
name
,description
, orsku
fields, or in the brand name.
example
Response
Get a Product
GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}Request
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- product_id in path - integerrequired
The ID of the
Product
to which the resource belongs. - include in query - arrayA comma-separated list of sub-resources to return with a product object.Type: array[string]
Allowed: bulk_pricing_rules | reviews | modifiers | options | parent_relations | custom_fields | channels | videos
- include_fields in query - arrayFields to include, in a comma-separated list. The ID and the specified fields will be returned.Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
- exclude_fields in query - arrayFields 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
dataobject
Base Product response
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
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- product_id in path - integerrequired
The ID of the
Product
to which the resource belongs. - Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
- include_fields in query - arraySub-resources to include on a product, in a comma-separated list. If
options
ormodifiers
is used, results are limited to 10 per page. The ID and the specified fields will be returned.Type: array[string]Allowed: variants | images | custom_fields | bulk_pricing_rules | primary_image | modifiers | options | videos
Body
namestring
>= 1 characters<= 250 charactersA unique product name.
Example: Smith Journal 13typestring
The product type. One of:
physical
- a physical stock unit,digital
- a digital download.Allowed: physical | digital
Example: physicalskustring
>= 0 characters<= 255 charactersA unique user-defined alphanumeric product code/stock keeping unit (SKU). The SKU is always unique regardless of the letter case for both products and variants.
Example: SM-13descriptionstring
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
Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store.
Min: 0Max: 9999999999widthnumber
Width of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999depthnumber
Depth of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999heightnumber
Height of the product, which can be used when calculating shipping costs.
Min: 0Max: 9999999999pricenumber
The price of the product. The price should include or exclude tax, based on the store settings.
Min: 0cost_pricenumber
The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
Min: 0retail_pricenumber
The retail cost of the product. If entered, the retail cost price will be shown on the product page.
Min: 0sale_pricenumber
If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost.
Min: 0map_pricenumber
Minimum Advertised Pricetax_class_idnumber
The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
Min: 0Max: 255product_tax_codestring
>= 0 characters<= 255 charactersTax 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.
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.
Min: 0Max: 1000brand_idinteger
You can add a product to an existing brand during a product /PUT or /POST. Use either the
brand_id
or thebrand_name
field. The response body can includebrand_id
.Min: 0Max: 1000000000brand_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 thebrand_id
or thebrand_name
field. The response body does not includebrand_name
.Example: Common Goodinventory_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.
Min: 0Max: 2147483647inventory_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.Min: 0Max: 2147483647inventory_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 theinventory_level
andinventory_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.
Min: 0is_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. Iffalse
, 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.warrantystring
>= 0 characters<= 65535 charactersWarranty information displayed on the product page. Can include HTML formatting.
bin_picking_numberstring
>= 0 characters<= 255 charactersThe BIN picking number for the product.
layout_filestring
>= 0 characters<= 500 charactersThe 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.
upcstring
>= 0 characters<= 14 charactersThe product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywordsstring
>= 0 characters<= 65535 charactersA comma-separated list of keywords that can be used to locate the product when searching the store.
availability_descriptionstring
>= 0 characters<= 255 charactersAvailability 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.'
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
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: -2147483648Max: 2147483647conditionstring
The product condition. Will be shown on the product page if the
is_condition_shown
fieldʼs value istrue
. 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.
Min: 0Max: 1000000000order_quantity_maximuminteger
The maximum quantity an order can contain when purchasing the product.
Min: 0Max: 1000000000page_titlestring
>= 0 characters<= 255 charactersCustom title for the product page. If not defined, the product name will be used as the meta title.
view_countinteger
deprecatedThe number of times the product has been viewed.
Min: 0Max: 1000000000preorder_release_datestring or null
Pre-order release date. See the
availability
field for details on setting a productʼs availability to accept pre-orders.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
toavailable
.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 setis_price_hidden
totrue
, theavailability
value must bedisabled
.)price_hidden_labelstring
>= 0 characters<= 200 charactersBy default, an empty string. If
is_price_hidden
istrue
, the value ofprice_hidden_label
is displayed instead of the price. (NOTE: To successfully set a non-empty string value withis_price_hidden
set totrue
, theavailability
value must bedisabled
.)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_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>= 0 characters<= 14 charactersmpnstring
Manufacturer Part Numberdate_last_importedstring
the date when the Product had been importedreviews_countinteger
The number of times the product has been rated.
Example: 4total_soldinteger
The total quantity of this product sold.
Example: 80custom_fieldsarray[object]
200 maximum custom fields per product. 255 maximum characters per custom field.Min: 0Max: 255bulk_pricing_rulesarray[object]
imagesarray[object]
videosarray[object]
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.
example
Response
Body
dataobject
Base Product response
example
Delete a Product
DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}Request
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- product_id in path - integerrequired
The ID of the
Product
to which the resource belongs.
example
Response
See something you can improve? Edit this file on GitHub