PUT /catalog/products

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

Required Fields

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

Read-Only Fields

id
date_created
date_modified
calculated_price
base_variant_id

Servers

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

Request headers

Name Type Required Description

Name	Type	Required	Description
`Accept`	String	Yes	The MIME type of the response body. Default value: "application/json"
`Content-Type`	String	Yes	The MIME type of the request body. Default value: "application/json"

Accept

String

Yes

The MIME type of the response body.

Default value: "application/json"

Content-Type

String

Yes

The MIME type of the request body.

Default value: "application/json"

Query parameters

Name	Type	Required	Description
`include_fields[]`	Array	No	Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

Request body fields

Name	Type	Required	Description
`[]`	Array	Yes
`[].retail_price`	Number	No	The retail cost of the product. If entered, the retail cost price will be shown on the product page.
`[].inventory_level`	Integer	No	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.
`[].width`	Number	No	Width of the product, which can be used when calculating shipping costs.
`[].layout_file`	String	No	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.
`[].depth`	Number	No	Depth of the product, which can be used when calculating shipping costs.
`[].id`	Integer	Yes	Unique ID of the Product. Read-Only.
`[].total_sold`	Integer	No	The total quantity of this product sold.
`[].open_graph_use_meta_description`	Boolean	No	Flag to determine if product description or open graph description is used.
`[].date_last_imported`	String	No	the date when the Product had been imported
`[].sku`	String	No	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.
`[].warranty`	String	No	Warranty information displayed on the product page. Can include HTML formatting.
`[].is_free_shipping`	Boolean	No	Flag used to indicate whether the product has free shipping. If `true`, the shipping cost for the product will be zero.
`[].type`	String	No	The product type. One of: `physical` - a physical stock unit, `digital` - a digital download. Valid values: `"digital"` `"physical"`
`[].inventory_warning_level`	Integer	No	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.
`[].upc`	String	No	The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
`[].gift_wrapping_options_list[]`	Array	No	A list of gift-wrapping option IDs. Always included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters.
`[].is_condition_shown`	Boolean	No	Flag used to determine whether the product condition is shown to the customer on the product page.
`[].open_graph_type`	String	No	Type of product, defaults to `product`. Valid values: `"game"` `"movie"` `"food"` `"song"` `"product"` `"book"` `"tv_show"` `"drink"` `"album"`
`[].videos[]`	Array	No	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.
`[].videos[].id`	Integer	No	The unique numeric ID of the product video; increments sequentially.
`[].videos[].sort_order`	Integer	No	The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered.
`[].videos[].description`	String	No	The description for the video. If left blank, this will be filled in according to data on a host site.
`[].videos[].video_id`	String	No	The ID of the video on a host site.
`[].videos[].length`	String	No	Length of the video. This will be filled in according to data on a host site.
`[].videos[].title`	String	No	The title for the video. If left blank, this will be filled in according to data on a host site.
`[].videos[].type`	String	No	The video type (a short name of a host site). Valid values: `"youtube"`
`[].videos[].product_id`	Integer	No	The unique numeric identifier for the product with which the image is associated.
`[].mpn`	String	No	Manufacturer Part Number
`[].open_graph_use_image`	Boolean	No	Flag to determine if product image or open graph image is used.
`[].height`	Number	No	Height of the product, which can be used when calculating shipping costs.
`[].open_graph_description`	String	No	Description to use for the product, if not specified then the meta_description will be used instead.
`[].custom_url`	Object	No	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.
`[].custom_url.url`	String	No	Product URL on the storefront.
`[].custom_url.is_customized`	Boolean	No	Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).
`[].custom_url.create_redirect`	Boolean	No	Optional field. This field automatically creates a dynamic 301 redirect when a product URL change occurs with a PUT request. Existing dynamic redirects will automatically update to a new URL to avoid a loop.
`[].open_graph_use_product_name`	Boolean	No	Flag to determine if product name or open graph name is used.
`[].inventory_tracking`	String	No	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. Valid values: `"variant"` `"product"` `"none"`
`[].map_price`	Number	No	Minimum Advertised Price
`[].reviews_rating_sum`	Integer	No	The total (cumulative) rating for the product.
`[].name`	String	No	A unique product name.
`[].page_title`	String	No	Custom title for the product page. If not defined, the product name will be used as the meta title.
`[].brand_id`	Integer	No	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`.
`[].reviews_count`	Integer	No	The number of times the product has been rated.
`[].images[]`	Array	No
`[].images[].id`	Integer	No	The unique numeric ID of the image; increments sequentially.
`[].images[].date_modified`	String	No	The date on which the product image was modified.
`[].images[].sort_order`	Integer	No	The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered.
`[].images[].is_thumbnail`	Boolean	No	Flag for identifying whether the image is used as the productʼs thumbnail.
`[].images[].description`	String	No	The description for the image.
`[].images[].url_standard`	String	No	The standard URL for this image. By default, this is used for product-page images.
`[].images[].url_zoom`	String	No	The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. You should provide an image smaller than 1280x1280; otherwise, the API returns a resized image.
`[].images[].url_thumbnail`	String	No	The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
`[].images[].url_tiny`	String	No	The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
`[].images[].product_id`	Integer	No	The unique numeric identifier for the product with which the image is associated.
`[].images[].image_url`	String	No	The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. Cannot be used with `image_file`.
`[].condition`	String	No	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`. Valid values: `"New"` `"Refurbished"` `"Used"`
`[].weight`	Number	No	Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store.
`[].availability_description`	String	No	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.'
`[].availability`	String	No	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. Valid values: `"available"` `"disabled"` `"preorder"`
`[].bin_picking_number`	String	No	The BIN picking number for the product.
`[].description`	String	No	The product description, which can include HTML formatting.
`[].cost_price`	Number	No	The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
`[].meta_description`	String	No	Custom meta description for the product page. If not defined, the storeʼs default meta description will be used.
`[].is_featured`	Boolean	No	Flag to determine whether the product should be included in the `featured products` panel when viewing the store.
`[].brand_name`	String	No	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`.
`[].fixed_cost_shipping_price`	Number	No	A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
`[].is_price_hidden`	Boolean	No	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`.)
`[].sort_order`	Integer	No	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.
`[].preorder_release_date`	String	No	Pre-order release date. See the `availability` field for details on setting a productʼs availability to accept pre-orders.
`[].categories[]`	Array	No	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.
`[].order_quantity_minimum`	Integer	No	The minimum quantity an order must contain, to be eligible to purchase this product.
`[].related_products[]`	Array	No	An array of IDs for the related products.
`[].custom_fields[]`	Array	No	200 maximum custom fields per product. 255 maximum characters per custom field.
`[].custom_fields[].id`	Integer	No	The unique numeric ID of the custom field; increments sequentially. Required to update existing custom field in /PUT request. Read-Only
`[].custom_fields[].name`	String	Yes	The name of the field, shown on the storefront, orders, etc. Required for /POST
`[].custom_fields[].value`	String	Yes	The name of the field, shown on the storefront, orders, etc. Required for /POST
`[].price`	Number	No	The price of the product. The price should include or exclude tax, based on the store settings.
`[].view_count`	Integer	No	The number of times the product has been viewed.
`[].price_hidden_label`	String	No	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`.)
`[].product_tax_code`	String	No	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.
`[].is_visible`	Boolean	No	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.
`[].order_quantity_maximum`	Integer	No	The maximum quantity an order can contain when purchasing the product.
`[].is_preorder_only`	Boolean	No	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`.
`[].meta_keywords[]`	Array	No	Custom meta keywords for the product page. If not defined, the storeʼs default keywords will be used.
`[].tax_class_id`	Number	No	The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
`[].gtin`	String	No	Global Trade Item Number
`[].sale_price`	Number	No	If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost.
`[].search_keywords`	String	No	A comma-separated list of keywords that can be used to locate the product when searching the store.
`[].preorder_message`	String	No	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.
`[].gift_wrapping_options_type`	String	No	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. Valid values: `"any"` `"list"` `"none"`
`[].open_graph_title`	String	No	Title of the product, if not specified the product name will be used instead.
`[].bulk_pricing_rules[]`	Array	No
`[].bulk_pricing_rules[].id`	Integer	Yes	Unique ID of the Bulk Pricing Rule. Read-Only.
`[].bulk_pricing_rules[].amount`	Object	Yes	You can express the adjustment type as either a fixed dollar amount or a percentage. Send a number; the response will return a number for `price` and `fixed` adjustments. Divide the adjustment percentage by 100 and send the result in string format. For example, represent 10% as “.10”. The response will return a float value for both `price` and `percentage` adjustments. Required in /POST.
`[].bulk_pricing_rules[].type`	String	Yes	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. Valid values: `"price"` `"fixed"` `"percent"`
`[].bulk_pricing_rules[].quantity_min`	Integer	Yes	The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. Required in /POST.
`[].bulk_pricing_rules[].quantity_max`	Integer	Yes	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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.