RESTAdminCatalogProducts

Create Product

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 a `video` object, see [Create a Product Video](/developer/api-reference/rest/admin/catalog/products/videos#create-a-product-video) for information.

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Query parameters

include_fieldslist of enumsOptional

Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

Request

This endpoint expects an object.
namestringRequired1-250 characters
A unique product name.
typeenumRequired

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

Allowed values:
weightdoubleRequired
Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store
pricedoubleRequired
The price of the product. The price should include or exclude tax, based on the store settings.
skustringOptional0-255 characters

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

descriptionstringOptional
The product description, which can include HTML formatting.
widthdoubleOptional
Width of the product, which can be used when calculating shipping costs.
depthdoubleOptional
Depth of the product, which can be used when calculating shipping costs.
heightdoubleOptional
Height of the product, which can be used when calculating shipping costs.
cost_pricedoubleOptional

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

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

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

map_pricedoubleOptional
Minimum Advertised Price
tax_class_iddoubleOptional0-255

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

product_tax_codestringOptional0-255 characters
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.
categorieslist of doublesOptional
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.
brand_idintegerOptional0-1000000000

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.

brand_namestringOptional
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`.
inventory_levelintegerOptional0-2147483647
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](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api).
inventory_warning_levelintegerOptional0-2147483647

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_trackingenumOptional
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:
fixed_cost_shipping_pricedoubleOptional

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

is_free_shippingbooleanOptional

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

is_visiblebooleanOptional

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.

related_productslist of integersOptional
An array of IDs for the related products.
warrantystringOptional0-65535 characters
Warranty information displayed on the product page. Can include HTML formatting.
bin_picking_numberstringOptional0-255 characters
The BIN picking number for the product.
layout_filestringOptional0-500 characters

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.

upcstringOptional0-14 characters
The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywordsstringOptional0-65535 characters

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

availability_descriptionstringOptional0-255 characters

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

availabilityenumOptional
Availability of the product. (Corresponds to the productʼs [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) 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 values:
gift_wrapping_options_typeenumOptional
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 values:
gift_wrapping_options_listlist of integersOptional

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_orderintegerOptional-2147483648-2147483647
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.
conditionenumOptional

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:
is_condition_shownbooleanOptional
Flag used to determine whether the product condition is shown to the customer on the product page.
order_quantity_minimumintegerOptional0-1000000000
The minimum quantity an order must contain, to be eligible to purchase this product.
order_quantity_maximumintegerOptional0-1000000000
The maximum quantity an order can contain when purchasing the product.
page_titlestringOptional0-255 characters
Custom title for the product page. If not defined, the product name will be used as the meta title.
meta_keywordslist of stringsOptional

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

meta_descriptionstringOptional0-65535 characters

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

preorder_release_datedatetime or nullOptional

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

preorder_messagestringOptional0-255 characters

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_onlybooleanOptional

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_hiddenbooleanOptional

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_labelstringOptional0-200 characters

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

custom_urlobjectOptional
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_typeenumOptional

Type of product, defaults to product.

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

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

open_graph_use_meta_descriptionbooleanOptional
Flag to determine if product description or open graph description is used.
open_graph_use_product_namebooleanOptional
Flag to determine if product name or open graph name is used.
open_graph_use_imagebooleanOptional
Flag to determine if product image or open graph image is used.
gtinstringOptional0-14 characters
Global Trade Item Number
mpnstringOptional
Manufacturer Part Number
date_last_importedstringOptional
the date when the Product had been imported
reviews_rating_sumintegerOptional

The total (cumulative) rating for the product.

reviews_countintegerOptional
The number of times the product has been rated.
total_soldintegerOptional
The total quantity of this product sold.
custom_fieldslist of objectsOptional
200 maximum custom fields per product. 255 maximum characters per custom field.
bulk_pricing_ruleslist of objectsOptional
imageslist of objectsOptional
videoslist of objectsOptional
The Catalog API integrates with third-party YouTube. The [YouTube Terms of Service](https://www.youtube.com/t/terms) and [Google Privacy Policy](https://policies.google.com/privacy) apply, as indicated in our [Privacy Policy](https://www.bigcommerce.com/privacy/) and [Terms of Service](https://www.bigcommerce.com/terms/).
variantslist of objectsOptional
view_countintegerOptional0-1000000000Deprecated
The number of times the product has been viewed.

Response

dataobject
metaobject
Response metadata.

Errors

409
Conflict Error
422
Unprocessable Entity Error