v1

latestSwagger 2.02026-07-17148179252.3 KB
Catalog

Creates a Product in the BigCommerce Catalog.

post/catalog/products

Request body

namestring

The product name.

type'physical' | 'digital'

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

skustring

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

descriptionstring

The product description, which can include HTML formatting.

weightnumber double

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

widthnumber double

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

depthnumber double

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

heightnumber double

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

pricenumber double

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

cost_pricenumber double

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

retail_pricenumber double

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

sale_pricenumber double

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

tax_class_idinteger

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

product_tax_codestring

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.

categoriesinteger[]

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_idinteger

The ID associated with the product's brand.

inventory_levelinteger

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

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.

inventory_tracking'none' | 'product' | 'variant'

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.

fixed_cost_shipping_pricenumber double

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

An array of IDs for the related products.

warrantystring

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

bin_picking_numberstring

The BIN picking number for the product.

layout_filestring

The layout template file used to render this product.

upcstring

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

search_keywordsstring

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

availability'available' | 'disabled' | 'preorder'

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.

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

gift_wrapping_options_type'any' | 'none' | 'list'

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.

gift_wrapping_options_listinteger[]

A list of gift-wrapping option IDs.

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.

condition'New' | 'Used' | 'Refurbished'

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.

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.

order_quantity_maximuminteger

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

page_titlestring

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

meta_keywordsstring[]

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

meta_descriptionstring

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

view_countinteger

The number of times the product has been viewed.

preorder_release_datestring date-time nullable

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.

is_preorder_onlyboolean

If set to false, the product will not change its availability from preorder to available on the release date. Otherwise, on the release date the product's availability/status will change 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.)

open_graph_type'product' | 'album' | 'book' | 'drink' | 'food' | 'game' | 'movie' | 'song' | 'tv_show'

Type of product, defaults to product.

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.

Response

A product.

metaMeta

Empty meta object; may be used later.