> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Products V2 > **Note** > > It is recommended to use the new [Catalog Products](/developer/api-reference/rest/admin/catalog). ## Products A product object represents a saleable item in the catalog. > **Note** > > #### Deprecated > > Avoid using this API operation if possible. It will be removed in a future version. #### Product Object Properties | Name | Type | Description | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | int | The unique numerical ID of the product. Increments sequentially. | | keyword\_filter | string | (This property is deprecated.) | | name | string | The product name. | | type | enum | The product type. One of: `physical` – a physical stock unit. `digital` – a digital download. | | sku | string | User-defined product code/stock keeping unit (SKU). | | description | text | Product description, which can include HTML formatting. | | search\_keywords | text | A comma-separated list of keywords that can be used to locate the product when searching the store. | | availability\_description | string | Availability text, displayed on the checkout page under the product title, telling the customer how long it will normally take to ship this product. E.g.: "Usually ships in 24 hours". | | price | decimal | The product's price. Should include, or exclude, tax based on the store settings. | | cost\_price | decimal | The product's cost price. Stored for reference only; not used or displayed anywhere on the store. | | retail\_price | decimal | The product's retail cost. If entered, this retail price will be shown on the product page. | | sale\_price | decimal | Sale price. If entered, this will be used instead of value in the price field when calculating the product's cost. | | calculated\_price | decimal | Price as displayed to guests, adjusted for applicable sales and rules. (Cart price might incorporate further discounts for logged-in customers or customer groups.) Read-only. | | sort\_order | int | 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. | | is\_visible | boolean | Flag to determine whether or not the product should be displayed to customers browsing. 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 for shoppers viewing the store. | | related\_products | string | Defaults to `-1`, which causes the store to automatically generate a list of related products. To manually specify the list of related products, include their IDs, separated by commas. For example: `3, 6, 7, 21`. | | inventory\_level | int | Current inventory level of the product. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take effect. | | inventory\_warning\_level | int | Inventory Warning level for the product. When the product's inventory level drops below this warning level, the store owner will be sent a notification. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take effect. | | warranty | text | Warranty information displayed on the product page. Can include HTML formatting. | | weight | decimal | Weight of the product, which can be used when calculating shipping costs. | | width | decimal | Width of the product, which can be used when calculating shipping costs. | | height | decimal | Height of the product, which can be used when calculating shipping costs. | | depth | decimal | Depth of the product, which can be used when calculating shipping costs. | | fixed\_cost\_shipping\_price | decimal | A fixed shipping cost for the product. If defined, this value will be used instead of normal shipping-cost calculation during checkout. | | is\_free\_shipping | boolean | Flag used to indicate whether or not the product has free shipping. If `true`, the shipping cost for the product will be zero. | | inventory\_tracking | enum | The type of inventory tracking for the product. One of: `none` – inventory levels will not be tracked. `simple` – inventory levels will be tracked using the `inventory_level` and `inventory_warning_level` fields. `sku` – inventory levels will be tracked based on individual product options, which maintain their own warning levels and inventory levels. | | rating\_total | int | The total rating for the product. | | rating\_count | int | The total number of ratings the product has had. | | total\_sold | int | Total quantity of this product sold through transactions. | | date\_created | date | The date of which the product was created. | | brand\_id | int | The product's brand | | view\_count | int | The number of times the product has been viewed. | | page\_title | string | Custom title for the product's page. If not defined, the product name will be used as the page title. | | meta\_keywords | text | Custom meta keywords for the product page. If not defined, the store's default keywords will be used. | | meta\_description | text | Custom meta description for the product page. If not defined, the store's default meta description will be used. | | layout\_file | string | DEPRECATED. The layout template file used to render this product. This field is writable only for stores with a Blueprint theme applied. For Stencil stores, use the V3 Custom Templates API. | | is\_price\_hidden | boolean | The default `false` value indicates that this product's price should be shown on the product page. If set to `true`, the price will be 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` will be displayed instead of the price. (NOTE: To successfully set a non-empty string value for `price_hidden_label`, the `availability` value must be `disabled`.) | | categories | array | An array of IDs for the categories this product belongs to. When updating a product, if an array of categories is supplied, then all product categories will be overwritten. Does not accept more than 1,000 ID values. | | date\_modified | date | The date that the product was last modified. | | event\_date\_field\_name | string | Name of the field to be displayed on the product page when selecting the event/delivery date. | | event\_date\_type | enum | One of the following values: `none` – Disables the event/delivery date requirement and field. `after` – The selected date must fall either on, or after, the date specified in the `event_date_start` field. `before` – The selected date must fall either before, or on, the date specified in the `event_date_end` field. `range` – The selected date must fall between the `event_date_start` and `event_date_end` dates. | | event\_date\_start | date | When the product requires the customer to select an event/delivery date, this date is used as the "after" date. | | event\_date\_end | date | When the product requires the customer to select an event/delivery date, this date is used as the "before" date. | | myob\_asset\_account | string | MYOB Asset Account. | | myob\_income\_account | string | MYOB Income Account. | | myob\_expense\_account | string | MYOB Expense/COS Account. | | peachtree\_gl\_account | string | Peachtree General Ledger Account. | | condition | enum | The product's condition. Will be shown on the product page if the value of the `is_condition_shown` field is true. Possible values: `New`, `Used`, `Refurbished`. | | is\_condition\_shown | boolean | Flag used to determine whether the product's condition will be shown to the customer on the product page. | | preorder\_release\_date | date | Pre-order release date. See `availability` field for details on setting a product's availability to accept pre-orders. | | is\_preorder\_only | boolean | 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`. | | 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 replaced with the release date. | | order\_quantity\_minimum | int | The minimum quantity an order must contain in order to purchase this product. | | order\_quantity\_maximum | int | The maximum quantity an order can contain when purchasing the product. | | open\_graph\_type | enum | Type of product. Acceptable values are: `product`, `album`, `book`, `drink`, `food`, `game`, `movie`, `song`, `tv_show` | | open\_graph\_title | string | Title of the product. If not specified, the product's name will be used instead. | | open\_graph\_description | text | Description to use for the product. If not specified, the `meta_description` will be used instead. | | is\_open\_graph\_thumbnail | boolean | If set to `true`, the product thumbnail image will be used as the open graph image. | | upc | string | The product UPC code, which is used in feeds for shopping comparison sites. | | date\_last\_imported | date | The date on which the product was last imported using the bulk importer. | | option\_set\_id | int | The ID of the [option set](/developer/docs/admin/catalog-and-inventory) applied to the product. (NOTE: To remove the option set from the product, set the value to `null` on update.) | | tax\_class\_id | int | The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.) | | option\_set\_display | enum | The position on the product page where options from the option set will be displayed. | | bin\_picking\_number | string | The BIN picking number for the product. | | custom\_url | string | Custom URL (if set) overriding the structure dictated in the store's settings. If no custom URL is set, this will contain the default URL. | | primary\_image | object | An image object, corresponding to the image that is set as the product's thumbnail. This object includes that image's `id`, plus four URL values identifying where to pull the image at different sizes: `standard_url` is the image used in the product page's image box. `tiny_url` is the thumbnail image displayed below the product page's image box. `thumbnail_url` is used for product list-box images on category pages and in side panels. `zoom_url` is either the original image size provided to BigCommerce, or the merchant-selected `Product Zoom Image`/`Zoomed image` size – whichever is smaller. (You can always access the product's original image via the [Product Images](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-images) resource.) | | availability | enum | Availability of the product. Possible values: `available` – the product can be purchased on the storefront. `disabled` - the product is listed on the storefront, but cannot be purchased. `preorder` – the product is listed for pre-orders. | | brand | resource | The product's brand | | downloads | resource | Total number of downloads for a downloadable product. | | images | resource | See the [Product Images](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-images) resource for information. | | discount\_rules | resource | See the [Bulk Pricing](/developer/docs/archive/store-operations/v2-catalog-products/v2-bulk-pricing) resource for information. | | configurable\_fields | resource | Configurable fields for the product. | | custom\_fields | resource | See the [Custom Fields](/developer/docs/archive/store-operations/v2-catalog-products/v2-custom-fields) resource for information. | | videos | resource | See the [Product Videos](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-videos) resource for information. | | skus | resource | Stock Keeping Units for the product. See the [Product SKU](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-sku) resource for the definition of a sku object. | | rules | resource | Rules that apply only to this product, based on the product's option set. See the [Product Rules](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-rules) resource for information. | | option\_set | resource | See the [Option Sets](/developer/docs/archive/store-operations/v2-catalog-products/v2-option-sets) resource for information. | | options | resource | Options from the option set applied to the product. See the [Product Options](/developer/docs/archive/store-operations/v2-catalog-products/v2-product-options) resource for information. | | tax\_class | resource | Assigned tax class, when using a manual tax setup. This can be a number matching one of the tax classes set up in your store. | | avalara\_product\_tax\_code | resource | 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 Avalara Premium 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 [overview](https://help.avalara.com/000_Avalara_AvaTax/Manage_Product_Taxability/010_Select_AvaTax_System_Tax_Codes) and [FAQ](https://help.avalara.com/000_Avalara_AvaTax/Manage_Product_Taxability/Tax_Codes_-_Frequently_Asked_Questions) on AvaTax System Tax Codes. You can also [download codes](https://help.avalara.com/@api/deki/files/1675/AvaTax_System_Tax_Codes_Toolkit.zip?revision=37) as a zipfile of spreadsheets, or [search or browse codes](https://taxcode.avatax.avalara.com/) in Avalara's Tax Code Search Tool. (These external links are subject to change.) | #### List Products Gets the collection of products. (Default sorting is by product id, from lowest to highest.) > `GET /stores/{store_hash}/v2/products` ### Filters Filter parameters can be added to the URL query string to select specific products in the collection. | Parameter | Type | Example | | ------------------------- | ---------------- | ------------------------------------------------- | | min\_id | int | `/api/v2/products?min_id={value}` | | max\_id | int | `/api/v2/products?max_id={value}` | | name | string | `/api/v2/products?name={value}` | | keyword\_filter | string | `/api/v2/products?keyword_filter={value}` | | description | string | `/api/v2/products?description={value}` | | sku | string | `/api/v2/products?sku={value}` | | condition | string | `/api/v2/products?condition={value}` | | availability | string | `/api/v2/products?availability={value}` | | brand\_id | string | `/api/v2/products?brand_id={value}` | | min\_date\_created | dateTime or date | `/api/v2/products?min_date_created={value}` | | max\_date\_created | dateTime or date | `/api/v2/products?max_date_created={value}` | | min\_date\_modified | dateTime or date | `/api/v2/products?min_date_modified={value}` | | max\_date\_modified | dateTime or date | `/api/v2/products?max_date_modified={value}` | | min\_date\_last\_imported | date | `/api/v2/products?min_date_last_imported={value}` | | max\_date\_last\_imported | date | `/api/v2/products?max_date_last_imported={value}` | | min\_price | decimal | `/api/v2/products?min_price={value}` | | max\_price | decimal | `/api/v2/products?max_price={value}` | | min\_number\_sold | int | `/api/v2/products?min_number_sold={value}` | | max\_number\_sold | int | `/api/v2/products?max_number_sold={value}` | | is\_visible | string | `/api/v2/products?is_visible={value}` | | is\_featured | string | `/api/v2/products?is_featured={value}` | | min\_inventory\_level | int | `/api/v2/products?min_inventory_level={value}` | | max\_inventory\_level | int | `/api/v2/products?max_inventory_level={value}` | | include\_sku | boolean | `/api/v2/products?include_sku={value}` | | category | string | `/api/v2/products?category={value}` | | product\_tax\_code | string | `/api/v2/products?product_tax_code={value}` | ### Pagination Parameters can be added to the URL query string to paginate the collection. The maximum limit is 250. If a limit isn’t provided, up to 50 products are returned by default. | Parameter | Type | Example | | --------- | ---- | -------------------------------- | | Page | int | `/api/v2/products?page={number}` | | Limit | int | `/api/v2/products?limit={count}` | **Note** You can filter the retrieved fields by appending one of the following options to your request: * ?include= * ?include=@summary * ?exclude= For details, syntax, and examples, please see the [Get a Product](#get-a-product) operation. ### Response Example JSON returned in the response: ```json showLineNumbers={false} [ { "id": 32, "keyword_filter": null, "name": "[Sample] Tomorrow is today, Red printed scarf", "type": "physical", "sku": "", "description": "Densely pack your descriptions with useful information and watch products fly off the shelf.", "search_keywords": null, "availability_description": "", "price": "89.0000", "cost_price": "0.0000", "retail_price": "0.0000", "sale_price": "0.0000", "calculated_price": "89.0000", "sort_order": 0, "is_visible": true, "is_featured": true, "related_products": "-1", "inventory_level": 0, "inventory_warning_level": 0, "warranty": null, "weight": "0.3000", "width": "0.0000", "height": "0.0000", "depth": "0.0000", "fixed_cost_shipping_price": "10.0000", "is_free_shipping": false, "inventory_tracking": "none", "rating_total": 0, "rating_count": 0, "total_sold": 0, "date_created": "Fri, 21 Sep 2012 02:31:01 +0000", "brand_id": 17, "view_count": 4, "page_title": "", "meta_keywords": null, "meta_description": null, "layout_file": "product.html", "is_price_hidden": false, "price_hidden_label": "", "categories": [ 14 ], "date_modified": "Mon, 24 Sep 2012 01:34:57 +0000", "event_date_field_name": "Delivery Date", "event_date_type": "none", "event_date_start": "", "event_date_end": "", "myob_asset_account": "", "myob_income_account": "", "myob_expense_account": "", "peachtree_gl_account": "", "condition": "New", "is_condition_shown": false, "preorder_release_date": "", "is_preorder_only": false, "preorder_message": "", "order_quantity_minimum": 0, "order_quantity_maximum": 0, "open_graph_type": "product", "open_graph_title": "", "open_graph_description": null, "is_open_graph_thumbnail": true, "upc": null, "avalara_product_tax_code": "", "date_last_imported": "", "option_set_id": null, "tax_class_id": 0, "option_set_display": "right", "bin_picking_number": "", "custom_url": "/tomorrow-is-today-red-printed-scarf/", "primary_image": { "id": 247, "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.1280.1280.jpg?c=1", "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.220.290.jpg?c=1", "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.386.513.jpg?c=1", "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.44.58.jpg?c=1" }, "availability": "available", "brand": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/17.json", "resource": "/brands/17" }, "images": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/images.json", "resource": "/products/32/images" }, "discount_rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/discountrules.json", "resource": "/products/32/discountrules" }, "configurable_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/configurablefields.json", "resource": "/products/32/configurablefields" }, "custom_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/customfields.json", "resource": "/products/32/customfields" }, "videos": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/videos.json", "resource": "/products/32/videos" }, "skus": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/skus.json", "resource": "/products/32/skus" }, "rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/rules.json", "resource": "/products/32/rules" }, "option_set": null, "options": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/options.json", "resource": "/products/32/options" }, "tax_class": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json", "resource": "/taxclasses/0" } }, { "id": 33, "keyword_filter": null, "name": "[Sample] Anna, multi-colored bangles", "type": "physical", "sku": "", "description": "One of the best things you can do to make your store successful is invest some time in writing great product descriptions.

", "search_keywords": null, "availability_description": "", "price": "59.0000", "cost_price": "0.0000", "retail_price": "0.0000", "sale_price": "0.0000", "calculated_price": "59.0000", "sort_order": 0, "is_visible": true, "is_featured": true, "related_products": "-1", "inventory_level": 0, "inventory_warning_level": 0, "warranty": null, "weight": "0.5000", "width": "0.0000", "height": "0.0000", "depth": "0.0000", "fixed_cost_shipping_price": "0.0000", "is_free_shipping": false, "inventory_tracking": "none", "rating_total": 0, "rating_count": 0, "total_sold": 0, "date_created": "Fri, 21 Sep 2012 02:46:41 +0000", "brand_id": 18, "view_count": 12, "page_title": "", "meta_keywords": null, "meta_description": null, "layout_file": "product.html", "is_price_hidden": false, "price_hidden_label": "", "categories": [ 14 ], "date_modified": "Mon, 24 Sep 2012 05:28:02 +0000", "event_date_field_name": "Delivery Date", "event_date_type": "none", "event_date_start": "", "event_date_end": "", "myob_asset_account": "", "myob_income_account": "", "myob_expense_account": "", "peachtree_gl_account": "", "condition": "New", "is_condition_shown": false, "preorder_release_date": "", "is_preorder_only": false, "preorder_message": "", "order_quantity_minimum": 0, "order_quantity_maximum": 0, "open_graph_type": "product", "open_graph_title": "", "open_graph_description": null, "is_open_graph_thumbnail": true, "upc": null, "avalara_product_tax_code": "", "date_last_imported": "", "option_set_id": 13, "tax_class_id": 0, "option_set_display": "right", "bin_picking_number": "", "custom_url": "/anna-multi-colored-bangles/", "primary_image": { "id": 245, "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.1280.1280.jpg?c=1", "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.220.290.jpg?c=1", "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.386.513.jpg?c=1", "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.44.58.jpg?c=1" }, "availability": "available", "brand": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/18.json", "resource": "/brands/18" }, "images": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/images.json", "resource": "/products/33/images" }, "discount_rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/discountrules.json", "resource": "/products/33/discountrules" }, "configurable_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/configurablefields.json", "resource": "/products/33/configurablefields" }, "custom_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/customfields.json", "resource": "/products/33/customfields" }, "videos": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/videos.json", "resource": "/products/33/videos" }, "skus": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/skus.json", "resource": "/products/33/skus" }, "rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/rules.json", "resource": "/products/33/rules" }, "option_set": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/optionsets/13.json", "resource": "/optionsets/13" }, "options": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/options.json", "resource": "/products/33/options" }, "tax_class": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json", "resource": "/taxclasses/0" } } ] ``` #### Get a Product Gets a product. > `GET /stores/{store_hash}/v2/products/{id}` **Note** You can filter the retrieved fields by appending one of the following options to your request: * `?include=` * `?include=@summary` * `?exclude=` In particular, you can reduce payload size, and improve performance, by excluding the `description` field. ### Mandatory Fields However, the following fields are always present on product API requests, and cannot be excluded: * `id` * `name` * `date_modified` * `primary_image` ### include The following sample request will retrieve *only* the specified `date_created`, `price`, and `cost_price` fields, plus the mandatory fields listed just above: ``` https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?include=date_created,price,cost_price ``` Here is a corresponding sample response: ```json showLineNumbers={false} { "id": 32, "name": "[Sample] Tomorrow is today, Red printed scarf", "price": "89.0000", "cost_price": "0.0000", "date_created": "Fri, 21 Sep 2012 02:31:01 +0000", "date_modified": "Thu, 10 Dec 2015 21:10:17 +0000", "primary_image": { "id": 247, "tiny_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.60.90.jpg?c=1", "standard_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.500.750.jpg?c=1", "thumbnail_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.190.285.jpg?c=1", "zoom_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.1280.1280.jpg?c=1" }, "metadata": [] } ``` ### include=@summary The `?include=@summary` option retrieves the following predefined subset of fields, in addition to the [mandatory fields](#mandatory-fields) listed above: * `availability` * `calculated_price` * `inventory_tracking` * `sku` * `inventory_level` * `inventory_warning_level` * `is_visible` * `is_featured` Here is a sample request with the `?include=@summary` option appended: ``` https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?include=@summary ``` Here is a corresponding sample response: ```json showLineNumbers={false} { "id": 32, "name": "[Sample] Tomorrow is today, Red printed scarf", "sku": "TTRPS", "calculated_price": "89.0000", "is_visible": true, "is_featured": true, "inventory_level": 0, "inventory_warning_level": 0, "inventory_tracking": "none", "date_modified": "Thu, 10 Dec 2015 21:10:17 +0000", "availability": "available", "primary_image": { "id": 247, "tiny_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.60.90.jpg?c=1", "standard_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.500.750.jpg?c=1", "thumbnail_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.190.285.jpg?c=1", "zoom_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.1280.1280.jpg?c=1" }, "metadata": [] } ``` ### exclude The `?exclude=` option excludes one or more specified fields. However, you cannot exclude the mandatory `id`, `name`, `date_modified`, or `primary_image` fields. Here is a sample request with the `?exclude=` option appended: ``` https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?exclude=description ``` We have omitted the corresponding sample response. However, the following section shows a complete sample response for a request submitted with no `?include` or `?exclude` option. (The effect of the `?exclude=description` option shown above would be to omit the `"description": ` field shown as the sixth field below.) ### Response Example JSON returned in the response: ```json showLineNumbers={false} { "id": 32, "keyword_filter": null, "name": "[Sample] Tomorrow is today, Red printed scarf", "type": "physical", "sku": "", "description": "Densely pack your descriptions with useful information and watch products fly off the shelf.", "search_keywords": null, "availability_description": "", "price": "89.0000", "cost_price": "0.0000", "retail_price": "0.0000", "sale_price": "0.0000", "calculated_price": "89.0000", "sort_order": 0, "is_visible": true, "is_featured": true, "related_products": "-1", "inventory_level": 0, "inventory_warning_level": 0, "warranty": null, "weight": "0.3000", "width": "0.0000", "height": "0.0000", "depth": "0.0000", "fixed_cost_shipping_price": "10.0000", "is_free_shipping": false, "inventory_tracking": "none", "rating_total": 0, "rating_count": 0, "total_sold": 0, "date_created": "Fri, 21 Sep 2012 02:31:01 +0000", "brand_id": 17, "view_count": 4, "page_title": "", "meta_keywords": null, "meta_description": null, "layout_file": "product.html", "is_price_hidden": false, "price_hidden_label": "", "categories": [ 14 ], "date_modified": "Mon, 24 Sep 2012 01:34:57 +0000", "event_date_field_name": "Delivery Date", "event_date_type": "none", "event_date_start": "", "event_date_end": "", "myob_asset_account": "", "myob_income_account": "", "myob_expense_account": "", "peachtree_gl_account": "", "condition": "New", "is_condition_shown": false, "preorder_release_date": "", "is_preorder_only": false, "preorder_message": "", "order_quantity_minimum": 0, "order_quantity_maximum": 0, "open_graph_type": "product", "open_graph_title": "", "open_graph_description": null, "is_open_graph_thumbnail": true, "upc": null, "avalara_product_tax_code": "", "date_last_imported": "", "option_set_id": null, "tax_class_id": 0, "option_set_display": "right", "bin_picking_number": "", "custom_url": "/tomorrow-is-today-red-printed-scarf/", "primary_image": { "id": 247, "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.1280.1280.jpg?c=1", "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.220.290.jpg?c=1", "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.386.513.jpg?c=1", "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.44.58.jpg?c=1" }, "availability": "available", "brand": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/17.json", "resource": "/brands/17" }, "images": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/images.json", "resource": "/products/32/images" }, "discount_rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/discountrules.json", "resource": "/products/32/discountrules" }, "configurable_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/configurablefields.json", "resource": "/products/32/configurablefields" }, "custom_fields": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/customfields.json", "resource": "/products/32/customfields" }, "videos": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/videos.json", "resource": "/products/32/videos" }, "skus": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/skus.json", "resource": "/products/32/skus" }, "rules": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/rules.json", "resource": "/products/32/rules" }, "option_set": null, "options": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/options.json", "resource": "/products/32/options" }, "tax_class": { "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json", "resource": "/taxclasses/0" } } ``` #### Get a Product Count Gets a count of products. > `GET /stores/{store_hash}/v2/products/count` ### Filters Filter parameters can be added to the URL query string to select specific products in the collection. | Parameter | Type | Example | | ------------------------- | ------- | ------------------------------------------------- | | min\_id | int | `/api/v2/products?min_id={value}` | | max\_id | int | `/api/v2/products?max_id={value}` | | name | string | `/api/v2/products?name={value}` | | keyword\_filter | string | `/api/v2/products?keyword_filter={value}` | | description | string | `/api/v2/products?description={value}` | | sku | string | `/api/v2/products?sku={value}` | | condition | string | `/api/v2/products?condition={value}` | | availability | string | `/api/v2/products?availability={value}` | | brand\_id | string | `/api/v2/products?brand_id={value}` | | min\_date\_created | date | `/api/v2/products?min_date_created={value}` | | max\_date\_created | date | `/api/v2/products?max_date_created={value}` | | min\_date\_modified | date | `/api/v2/products?min_date_modified={value}` | | max\_date\_modified | date | `/api/v2/products?max_date_modified={value}` | | min\_date\_last\_imported | date | `/api/v2/products?min_date_last_imported={value}` | | max\_date\_last\_imported | date | `/api/v2/products?max_date_last_imported={value}` | | min\_price | decimal | `/api/v2/products?min_price={value}` | | max\_price | decimal | `/api/v2/products?max_price={value}` | | min\_number\_sold | int | `/api/v2/products?min_number_sold={value}` | | max\_number\_sold | int | `/api/v2/products?max_number_sold={value}` | | is\_visible | string | `/api/v2/products?is_visible={value}` | | is\_featured | string | `/api/v2/products?is_featured={value}` | | min\_inventory\_level | int | `/api/v2/products?min_inventory_level={value}` | | max\_inventory\_level | int | `/api/v2/products?max_inventory_level={value}` | | include\_sku | boolean | `/api/v2/products?include_sku={value}` | | category | string | `/api/v2/products?category={value}` | | product\_tax\_code | string | `/api/v2/products?product_tax_code={value}` | **Note** If no filters are applied, the total number of products is returned. ### Response Example JSON returned in the response: ```json showLineNumbers={false} { "count": 44 } ``` #### Create a Product Creates a new product. The example request shows how to create a basic product by sending a product object with the minimum required properties. > `POST /stores/{store_hash}/v2/products` ### Read-only Properties The following properties of the product are read-only. If one or more of these properties are included in the request, it will be rejected. * id * calculated\_price * brand * images * discount\_rules * configurable\_fields * custom\_fields * primary\_image * videos * rules * option\_set * options * tax\_class ### Requirements The following properties of the product are required. The request won’t be fulfilled unless these properties are valid. * name * price * categories * type * availability * weight **Note** Create a request by sending a [product object](#product-object-properties) with the minimum required properties: ```json showLineNumbers={false} { "name": "Plain T-Shirt", "type": "physical", "description": "This timeless fashion staple will never go out of style!", "price": "29.99", "categories": [18], "availability": "available", "weight": "0.5" } ``` When the `is_visible` property is not provided, the product's visibility is `false` by default. To make newly created products immediately visible on the storefront, you must set `is_visible` to `true` when you create each product. You may encounter a case where product information was updated successfully, but related inventory data failed to update. In such cases, BigCommerce will return a `207` status along with the object as updated and a descriptive error message. ``` 207 Multi-Status ``` To maximize system performance, BigCommerce caps the number of categories to which a product can belong. The maximum is 1,000. If your `POST` includes an array of more than 1,000 `categories` ID values, BigCommerce will return a 403 error: ``` 403 Access Denied/Forbidden ``` If automatic tax is enabled on the store, the value of `tax_class_id` will have no effect on the calculation of taxes. #### Update a Product Updates an existing product. > `PUT /stores/{store_hash}/v2/products/{id}` ### Read-only Properties The following properties of the product are read-only. If one or more of these properties are included in the request, it will be rejected. * id * rating\_total * rating\_count * number\_sold * date\_created * date\_modified * date\_last\_imported * calculated\_price * brand * images * discount\_rules * configurable\_fields * custom\_fields * primary\_image * videos * rules * option\_set * options * tax\_class ### Requirements There are no required properties when updating a product. **Note** To update a product, set one or more product properties in the `PUT` request: ```json showLineNumbers={false} { "custom_url": "/plain-tshirt/", "is_visible": true } ``` For example, you can use a `PUT` to link a product to an option set: ```json showLineNumbers={false} { "option_set_id": 14 } ``` Invalid property values will produce a `400 Bad Request` error response: ### Request ```json showLineNumbers={false} { "condition": "Worn" } ``` ### Response ``` 400 Bad Request ``` Trying to set read-only properties will also produce a `400 Bad Request` error response: ### Request ```json showLineNumbers={false} { "number_sold": 99 } ``` ### Response ``` 400 Bad Request ``` You may encounter a case where product information was updated successfully, but related inventory data failed to update. In such cases, BigCommerce will return a `207` status along with the object as updated and a descriptive error message. ``` 207 Multi-Status ``` To maximize system performance, BigCommerce caps the maximum number of categories to which a product can belong, at 1,000. If your `PUT` includes an array of more than 1,000 `categories` ID values, BigCommerce will return a `403` error: ``` 403 Access Denied/Forbidden ``` If automatic tax is enabled on the store, the value of `tax_class_id` will have no effect on the calculation of taxes. #### Delete a Product Deletes a product. > `DELETE /stores/{store_hash}/v2/products/{id}` **Note** Successful deletion of a product returns a `204 No Content` response: ``` 204 No Content ``` #### Delete All Products Deletes all products from the store. > `DELETE /stores/{store_hash}/v2/products` **Note** Successful deletion of all products returns a `204 No Content` response: ``` 204 No Content ```