Catalog
Catalog
Brands
Category
Product Metafields
Product Bulk Pricing Rules
Product Complex Rules
Product Custom Fields
Product Images
Product Modifiers
Product Variants
Product Variants Metafields
Product Variant Options
Product Reviews
Product Videos
Models
Customers & Subscribers
Price Lists
Marketing
Shipping
post

/catalog/products

Create a product. Only one product can be created at a time.

Authorization

apiKey
apiKey

Request Parameters

2 Headers

Request Body

3 Examples
Schema
object

Common Product properties.

name
string

The product name.

minLength: 1
maxLength: 255
example: Smith Journal 13
type
string

The product type. One of: physical - a physical stock unit, digital - a digital download.

Allowed Values: physical, digital
example: physical
sku
string

User defined product code/stock keeping unit (SKU).

minLength: 0
maxLength: 255
example: SM-13
description
string

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>
weight
number

Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store

format: double
minimum: 0
maximum: 9999999999
example: 1
width
number

Width of the product, which can be used when calculating shipping costs.

format: double
minimum: 0
maximum: 9999999999
example: 4.5
depth
number

Depth of the product, which can be used when calculating shipping costs.

format: double
minimum: 0
maximum: 9999999999
example: 2.6
height
number

Height of the product, which can be used when calculating shipping costs.

format: double
minimum: 0
maximum: 9999999999
example: 2
price
number

The price of the product. The price should include or exclude tax, based on the store settings.

format: double
minimum: 0
example: 25
cost_price
number

The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.

format: double
minimum: 0
retail_price
number

The retail cost of the product. If entered, the retail cost price will be shown on the product page.

format: double
minimum: 0
sale_price
number

If entered, the sale price will be used instead of value in the price field when calculating the product’s cost.

format: double
minimum: 0
tax_class_id
integer

The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)

minimum: 0
maximum: 1000000000
product_tax_code
string

Accepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce’s Avalara Premium integration can calculate sales taxes more accurately. Stores without Avalara Premium will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see Avalara’s documentation.

minLength: 0
maxLength: 255
categories
array[integer]

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.

brand_id
integer

A product can be added to an existing brand during a product /PUT or /POST.

minimum: 0
maximum: 1000000000
inventory_level
integer

Current inventory level of the product. Simple inventory tracking must be enabled (See the inventory_tracking field) for this to take any effect.

minimum: 0
maximum: 1000000000
inventory_warning_level
integer

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.

minimum: 0
maximum: 1000000000
inventory_tracking
string

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 Values: none, product, variant
fixed_cost_shipping_price
number

A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

format: double
minimum: 0
is_free_shipping
boolean

Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.

is_visible
boolean

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_featured
boolean

Flag to determine whether the product should be included in the featured products panel when viewing the store.

related_products
array[integer]

An array of IDs for the related products.

warranty
string

Warranty information displayed on the product page. Can include HTML formatting.

minLength: 0
maxLength: 65535
bin_picking_number
string

The BIN picking number for the product.

minLength: 0
maxLength: 255
layout_file
string

The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied.

minLength: 0
maxLength: 500
upc
string

The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.

minLength: 0
maxLength: 255
search_keywords
string

A comma-separated list of keywords that can be used to locate the product when searching the store.

minLength: 0
maxLength: 65535
availability
string

Availability of the product. Availability options are: available - the product can be purchased on the storefront; disabled - the product is listed in the storefront, but cannot be purchased; preorder - the product is listed for pre-orders.

Allowed Values: available, disabled, preorder
availability_description
string

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

minLength: 0
maxLength: 255
gift_wrapping_options_type
string

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.

Allowed Values: any, none, list
gift_wrapping_options_list
array[integer]

A list of gift-wrapping option IDs.

sort_order
integer

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.

minimum: -2147483648
maximum: 2147483647
condition
string

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 Values: New, Used, Refurbished
is_condition_shown
boolean

Flag used to determine whether the product condition is shown to the customer on the product page.

order_quantity_minimum
integer

The minimum quantity an order must contain, to be eligible to purchase this product.

minimum: 0
maximum: 1000000000
order_quantity_maximum
integer

The maximum quantity an order can contain when purchasing the product.

minimum: 0
maximum: 1000000000
page_title
string

Custom title for the product page. If not defined, the product name will be used as the meta title.

minLength: 0
maxLength: 255
meta_keywords
array[string]

Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.

meta_description
string

Custom meta description for the product page. If not defined, the store’s default meta description will be used.

minLength: 0
maxLength: 65535
view_count
integer

The number of times the product has been viewed.

minimum: 0
maximum: 1000000000
preorder_release_date
string

Pre-order release date. See the availability field for details on setting a product’s availability to accept pre-orders.

format: date-time
x-nullable: true
preorder_message
string

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.

minLength: 0
maxLength: 255
is_preorder_only
boolean

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_hidden
boolean

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_label
string

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

minLength: 0
maxLength: 200
custom_url
object

The custom URL for the product on the storefront.

url
string

Product URL on the storefront.

2 validations
is_customized
boolean

Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

open_graph_type
string

Type of product, defaults to product.

Allowed Values: product, album, book, drink, food, game, movie, song, tv_show
open_graph_title
string

Title of the product, if not specified the product name will be used instead.

open_graph_description
string

Description to use for the product, if not specified then the meta_description will be used instead.

open_graph_use_meta_description
boolean

Flag to determine if product description or open graph description is used.

open_graph_use_product_name
boolean

Flag to determine if product name or open graph name is used.

open_graph_use_image
boolean

Flag to determine if product image or open graph image is used.

brand_name
string

The brand can be created during a product /PUT or /POST request. If the brand already exists then the product will be added. If not the brand will be created and the product added. If using brand_name it performs a fuzzy match and adds the brand. eg. Common Good and Common good are the same. Brand name does not return as part of a product response. Only the brand_id.

example: Common Good
gtin
string

Global Trade Item Number

mpn
string

Manufacturer Part Number

custom_fields
array[object]
name
string

The name of the field, shown on the storefront, orders, etc. Required for /POST

4 validations + required
value
string

The name of the field, shown on the storefront, orders, etc. Required for /POST

4 validations + required
bulk_pricing_rules
array[object]
quantity_min
integer

The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. Required in /POST.

3 validations + required
quantity_max
integer

The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the quantity_min value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule. Required in /POST.

3 validations + required
type
string

The type of adjustment that is made. Values: price - the adjustment amount per product; percent - the adjustment as a percentage of the original price; fixed - the adjusted absolute price of the product. Required in /POST.

3 validations + required
amount
number

The value of the adjustment by the bulk pricing rule. Required in /POST.

4 validations + required
variants
array[object]
cost_price
number

The cost price of the variant. Not affected by Price List prices.

3 validations
price
number

This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.

3 validations
sale_price
number

This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s price field) will be used as the sale price.

3 validations
retail_price
number

This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s price field) will be used as the retail price.

3 validations
weight
number

This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.

3 validations
width
number

Width of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default width (set in the Product resource’s width field) will be used as the base width.

3 validations
height
number

Height of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default height (set in the Product resource’s height field) will be used as the base height.

3 validations
depth
number

Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default depth (set in the Product resource’s depth field) will be used as the base depth.

3 validations
is_free_shipping
boolean

Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

fixed_cost_shipping_price
number

A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

3 validations
purchasing_disabled
boolean

If true, this variant will not be purchasable on the storefront.

purchasing_disabled_message
string

If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

2 validations
image_url
string

The image that will be displayed when this variant is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF. Generic product images not specific to the variant should be stored on the product. Limit of 8MB per file.

1 validation
upc
string

The UPC code used in feeds for shopping comparison sites and external channel integrations.

1 validation
inventory_level
integer

Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.

1 validation
inventory_warning_level
integer

When the variant hits this inventory level, it is considered low stock.

1 validation
bin_picking_number
string

Identifies where in a warehouse the variant is located.

3 validations
product_id
integer
sku
string
3 validations
option_values
array[object]
1 validation

Responses

1 Example
Schema
object

Response payload for the BigCommerce API.

data
object
name
string

The product name.

4 validations
type
string

The product type. One of: physical - a physical stock unit, digital - a digital download.

3 validations
sku
string

User defined product code/stock keeping unit (SKU).

3 validations
description
string

The product description, which can include HTML formatting.

1 validation
weight
number

Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store

5 validations
width
number

Width of the product, which can be used when calculating shipping costs.

4 validations
depth
number

Depth of the product, which can be used when calculating shipping costs.

4 validations
height
number

Height of the product, which can be used when calculating shipping costs.

4 validations
price
number

The price of the product. The price should include or exclude tax, based on the store settings.

4 validations
cost_price
number

The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.

2 validations
retail_price
number

The retail cost of the product. If entered, the retail cost price will be shown on the product page.

2 validations
sale_price
number

If entered, the sale price will be used instead of value in the price field when calculating the product’s cost.

2 validations
tax_class_id
integer

The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)

2 validations
product_tax_code
string

Accepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce’s Avalara Premium integration can calculate sales taxes more accurately. Stores without Avalara Premium will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see Avalara’s documentation.

2 validations
categories
array[integer]

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.

1 validation
brand_id
integer

A product can be added to an existing brand during a product /PUT or /POST.

2 validations
inventory_level
integer

Current inventory level of the product. Simple inventory tracking must be enabled (See the inventory_tracking field) for this to take any effect.

2 validations
inventory_warning_level
integer

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.

2 validations
inventory_tracking
string

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.

1 validation
fixed_cost_shipping_price
number

A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

2 validations
is_free_shipping
boolean

Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.

is_visible
boolean

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_featured
boolean

Flag to determine whether the product should be included in the featured products panel when viewing the store.

related_products
array[integer]

An array of IDs for the related products.

warranty
string

Warranty information displayed on the product page. Can include HTML formatting.

2 validations
bin_picking_number
string

The BIN picking number for the product.

2 validations
layout_file
string

The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied.

2 validations
upc
string

The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.

2 validations
search_keywords
string

A comma-separated list of keywords that can be used to locate the product when searching the store.

2 validations
availability
string

Availability of the product. Availability options are: available - the product can be purchased on the storefront; disabled - the product is listed in the storefront, but cannot be purchased; preorder - the product is listed for pre-orders.

1 validation
availability_description
string

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

2 validations
gift_wrapping_options_type
string

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.

1 validation
gift_wrapping_options_list
array[integer]

A list of gift-wrapping option IDs.

sort_order
integer

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.

2 validations
condition
string

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.

1 validation
is_condition_shown
boolean

Flag used to determine whether the product condition is shown to the customer on the product page.

order_quantity_minimum
integer

The minimum quantity an order must contain, to be eligible to purchase this product.

2 validations
order_quantity_maximum
integer

The maximum quantity an order can contain when purchasing the product.

2 validations
page_title
string

Custom title for the product page. If not defined, the product name will be used as the meta title.

2 validations
meta_keywords
array[string]

Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.

meta_description
string

Custom meta description for the product page. If not defined, the store’s default meta description will be used.

2 validations
view_count
integer

The number of times the product has been viewed.

2 validations
preorder_release_date
string

Pre-order release date. See the availability field for details on setting a product’s availability to accept pre-orders.

2 validations
preorder_message
string

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.

2 validations
is_preorder_only
boolean

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_hidden
boolean

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_label
string

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

2 validations
custom_url
object

The custom URL for the product on the storefront.

open_graph_type
string

Type of product, defaults to product.

1 validation
open_graph_title
string

Title of the product, if not specified the product name will be used instead.

open_graph_description
string

Description to use for the product, if not specified then the meta_description will be used instead.

open_graph_use_meta_description
boolean

Flag to determine if product description or open graph description is used.

open_graph_use_product_name
boolean

Flag to determine if product name or open graph name is used.

open_graph_use_image
boolean

Flag to determine if product image or open graph image is used.

brand_name
string

The brand can be created during a product /PUT or /POST request. If the brand already exists then the product will be added. If not the brand will be created and the product added. If using brand_name it performs a fuzzy match and adds the brand. eg. Common Good and Common good are the same. Brand name does not return as part of a product response. Only the brand_id.

1 validation
gtin
string

Global Trade Item Number

mpn
string

Manufacturer Part Number

id
integer

The unique numeric ID of the product; increments sequentially.

calculated_price
number

The price of the product as seen on the storefront. It will be equal to the sale_price, if set, and the price if there is not a sale_price.

2 validations
reviews_rating_sum
integer

The total rating for the product.

1 validation
reviews_count
integer

The number of times the product has been rated.

1 validation
total_sold
integer

The total quantity of this product sold.

1 validation
custom_fields
array[object]
bulk_pricing_rules
array[object]
date_created
string

The date on which the product was created.

2 validations
date_modified
string

The date on which the product was modified.

2 validations
images
array[object]
videos
array[object]
variants
array[object]
base_variant_id
integer

The unique identifier of the base variant associated with a simple product. This value is null for complex products.

1 validation
meta
object

Empty meta object; may be used later.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
3 variables not set
store_hash
X-Auth-Client
X-Auth-Token