BigCommerce Catalog - Products is a powerful tool for online retailers to organize and display their inventory. This feature allows businesses to create and manage product listings, including detailed descriptions, pricing information, and images. With BigCommerce Catalog - Products, retailers can easily categorize their items, making it simple for customers to navigate and find the products they are looking for.
openapi: 3.0.3
info:
title: BigCommerce Catalog - Products
description: >-
> The Catalog API manages products, categories, brands, bulk pricing rules,
and more. To learn more about catalog resources, see the [Catalog
Overview](/docs/store-operations/catalog).
Our Catalog Products endpoints let you [create
products](/docs/rest-catalog/products#create-a-product), perform [batch
operations on existing
products](/docs/rest-catalog/products#update-products-batch) and work with
[reviews](/docs/rest-catalog/products/reviews),
[images](/docs/rest-catalog/products/images), and
[videos](/docs/rest-catalog/products/videos). Note that after a product is
created initially, you can manage the nuances of its variations using the
[Product Modifier](/docs/rest-catalog/product-modifiers), [Product
Variant](/docs/rest-catalog/product-variants), and [Product Variant
Options](/docs/rest-catalog/product-variant-options) endpoints.
Other core product endpoints focus on [bulk
pricing](/docs/rest-catalog/products/bulk-pricing-rules), [complex
rules](/docs/rest-catalog/products/complex-rules), [custom
fields](/docs/rest-catalog/products/custom-fields), and
[metafields](/docs/rest-catalog/products/metafields). Product Variant
objects also contain [their own
metafields](/docs/rest-catalog/product-variants/metafields). For
[MSF-enabled](/docs/storefront/multi-storefront) stores, the product object
also contains product [channel
assignments](/docs/rest-catalog/products/channel-assignments) and [category
assignments](/docs/rest-catalog/products/category-assignments); read more
about [products in the MSF
context](/docs/storefront/multi-storefront/guide#products).
This API family also contains an endpoint to [Get a catalog
summary](/docs/rest-catalog/products/summary).
> To learn more about authenticating Catalog endpoints, locate the
**Authentication** section at the top of each endpoint, then click **Show
Details**.
## Resources
### Webhooks
* [Product webhook events](/docs/integrations/webhooks/events#products)
* [Product assignment webhook
events](/docs/integrations/webhooks/events/channels#product-assignments)
### Additional Catalog endpoints
* [Brands](/docs/rest-catalog/brands)
* [Categories](/docs/rest-catalog/categories)
* [Category Trees](/docs/rest-catalog/category-trees)
* [Product Modifiers](/docs/rest-catalog/product-modifiers)
* [Product Variants](/docs/rest-catalog/product-variants)
* [Product Variant Options](/docs/rest-catalog/product-variant-options)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Batch Metafields
- name: Bulk Pricing Rules
- name: Category Assignments
- name: Channel Assignments
- name: Complex Rules
- name: Custom Fields
- name: Images
- name: Metafields
- name: Products
- name: Reviews
- name: Summary
- name: Videos
paths:
/catalog/products:
get:
tags:
- Products
summary: BigCommerce Get All Products
description: >-
Returns a list of **Products**. Optional filter parameters can be passed
in.
operationId: getProducts
parameters:
- name: id
in: query
description: |
Filter items by ID.
schema:
type: integer
- name: id:in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:not_in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:min
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:max
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:greater
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:less
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: name
in: query
description: |
Filter items by name.
schema:
type: string
- name: mpn
in: query
description: |
Filter items by Manufacturer Part Number (MPN).
schema:
type: string
- name: upc
in: query
description: |
Filter items by UPC.
schema:
type: string
- name: price
in: query
description: |
Filter items by price.
schema:
type: number
- name: weight
in: query
description: |
Filter items by weight.
schema:
type: number
- name: condition
in: query
description: |
Filter items by condition.
schema:
type: string
enum:
- new
- used
- refurbished
- name: brand_id
in: query
description: |
Filter items by brand_id.
schema:
type: integer
- name: date_modified
in: query
description: 'Filter items by `date_modified`. '
schema:
type: string
format: date-time
- name: date_modified:max
in: query
description: >-
Filter items by `date_modified`. For example,
`date_modified:max=2020-06-15`.
schema:
type: string
- name: date_modified:min
in: query
description: >-
Filter items by `date_modified`. For example,
`date_modified:min=2018-06-15`.
schema:
type: string
- name: date_last_imported
in: query
description: Filter items by date_last_imported.
schema:
type: string
format: date-time
- name: date_last_imported:not
in: query
description: >-
Filter items by date_last_imported. For example,
`date_last_imported:not=2015-08-21T22%3A53%3A23%2B00%3A00`.
schema:
type: string
- name: date_last_imported:max
in: query
description: >-
Filter items by date_last_imported. For example,
`date_last_imported:max=2015-08-21T22%3A53%3A23%2B00%3A00`.
schema:
type: string
- name: date_last_imported:min
in: query
description: >-
Filter items by date_last_imported. For example,
`date_last_imported:min=2015-08-21T22%3A53%3A23%2B00%3A00`.
schema:
type: string
- name: is_visible
in: query
description: >-
Filter items based on whether the product is currently visible on
the storefront.
schema:
type: boolean
- name: is_featured
in: query
description: Filter items by is_featured. `1` for true, `0` for false.
schema:
type: integer
enum:
- 1
- 0
- name: is_free_shipping
in: query
description: Filter items by is_free_shipping. `1` for true, `0` for false.
schema:
type: integer
- name: inventory_level
in: query
description: |
Filter items by inventory_level.
schema:
type: integer
- name: inventory_level:in
in: query
schema:
type: integer
- name: inventory_level:not_in
in: query
schema:
type: integer
- name: inventory_level:min
in: query
schema:
type: integer
- name: inventory_level:max
in: query
schema:
type: integer
- name: inventory_level:greater
in: query
schema:
type: integer
- name: inventory_level:less
in: query
schema:
type: integer
- name: inventory_low
in: query
description: |
Filter items by inventory_low. Values: 1, 0.
schema:
type: integer
- name: out_of_stock
in: query
description: >
Filter items by out_of_stock. To enable the filter, pass
`out_of_stock`=`1`.
schema:
type: integer
- name: total_sold
in: query
description: |
Filter items by total_sold.
schema:
type: integer
- name: type
in: query
description: Filter items by type.
schema:
type: string
enum:
- digital
- physical
- name: categories
in: query
description: |-
Filter items by categories.
If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`.
schema:
type: integer
- name: keyword
in: query
description: Filter items by keywords found in the `name` or `sku` fields
schema:
type: string
- name: keyword_context
in: query
description: >-
Set context used by the search algorithm to return results targeted
towards the specified group. Use `merchant` to help merchants search
their own catalog. Use `shopper` to return shopper-facing search
results.
schema:
type: string
enum:
- shopper
- merchant
- name: status
in: query
description: |
Filter items by status.
schema:
type: integer
- name: include
in: query
description: >-
Sub-resources to include on a product, in a comma-separated list. If
`options` or `modifiers` is used, results are limited to 10 per
page.
**Note:** The following sub-resources include:
* variants
* images
* custom_fields
* bulk_pricing_rules
* primary_image
* modifiers
* options
* videos
explode: false
schema:
type: array
items:
type: string
enum:
- variants
- images
- custom_fields
- bulk_pricing_rules
- primary_image
- modifiers
- options
- videos
- name: include_fields
in: query
description: >-
Fields to include, in a comma-separated list. The ID and the
specified fields will be returned.
schema:
type: string
- name: exclude_fields
in: query
description: >-
Fields to exclude, in a comma-separated list. The specified fields
will be excluded from a response. The ID cannot be excluded.
schema:
type: string
- name: availability
in: query
description: >
Filter items by availability. Values are: available, disabled,
preorder.
schema:
type: string
enum:
- available
- disabled
- preorder
- name: page
in: query
description: Specifies the page number in a limited (paginated) list of products.
schema:
type: integer
- name: limit
in: query
description: >-
Controls the number of items per page in a limited (paginated) list
of products. The default product limit is 50 with a maximum limit of
250.
schema:
type: integer
- name: direction
in: query
description: |
Sort direction. Acceptable values are: `asc`, `desc`.
schema:
type: string
enum:
- asc
- desc
- name: sort
in: query
description: >
Field name to sort by. Note: Since `id` increments when new products
are added, you can use that field to sort by product create date.
schema:
type: string
enum:
- id
- name
- sku
- price
- date_modified
- date_last_imported
- inventory_level
- is_visible
- total_sold
- name: categories:in
in: query
description: >-
Filter items by categories. Use for products in multiple categories.
For example, `categories:in=12,15`.
style: form
explode: false
schema:
type: array
items:
type: integer
- name: sku
in: query
description: >-
Filter items by main SKU. To filter by variant SKU, see [Get All
Variants](/docs/rest-catalog/product-variants#get-all-product-variants).
schema:
type: string
- name: sku:in
in: query
description: Filter items by SKU.
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: Get All Products Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/product_Full'
meta:
$ref: '#/components/schemas/metaCollection_Full'
put:
tags:
- Products
summary: BigCommerce Update Products (Batch)
description: |-
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`
operationId: updateProducts
parameters:
- $ref: '#/components/parameters/ContentType'
- name: include_fields
in: query
description: >-
Fields to include, in a comma-separated list. The ID and the
specified fields will be returned.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/product_Put_Collection'
examples:
example-1:
value:
- id: 0
name: Smith Journal 13
type: physical
sku: SM-13
description: >-
<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: 0
width: 0
depth: 0
height: 0
price: 0
cost_price: 0
retail_price: 0
sale_price: 0
map_price: 0
tax_class_id: 0
product_tax_code: string
categories:
- 0
brand_id: 0
inventory_level: 0
inventory_warning_level: 0
inventory_tracking: none
fixed_cost_shipping_price: 0
is_free_shipping: true
is_visible: true
is_featured: true
related_products:
- 0
warranty: string
bin_picking_number: string
layout_file: string
upc: string
search_keywords: string
availability: available
availability_description: string
gift_wrapping_options_type: any
gift_wrapping_options_list:
- 0
sort_order: -2147483648
condition: New
is_condition_shown: true
order_quantity_minimum: 0
order_quantity_maximum: 0
page_title: string
meta_keywords:
- string
meta_description: string
view_count: 0
preorder_release_date: '2019-08-24T14:15:22Z'
preorder_message: string
is_preorder_only: true
is_price_hidden: true
price_hidden_label: string
custom_url:
url: string
is_customized: true
open_graph_type: product
open_graph_title: string
open_graph_description: string
open_graph_use_meta_description: true
open_graph_use_product_name: true
open_graph_use_image: true
brand_name: Common Good
gtin: string
mpn: string
date_last_imported: '2015-07-03T18:16:02+00:00'
reviews_rating_sum: 3
reviews_count: 4
total_sold: 80
custom_fields:
- id: 6
name: ISBN
value: '1234567890123'
bulk_pricing_rules:
- id: 0
quantity_min: 10
quantity_max: 50
type: price
amount: 10
images:
- image_file: string
is_thumbnail: true
sort_order: -2147483648
description: string
image_url: string
id: 0
product_id: 0
url_zoom: string
url_standard: string
url_thumbnail: string
url_tiny: string
date_modified: '2019-08-24T14:15:22Z'
videos:
- title: Writing Great Documentation
description: A video about documentation.
sort_order: 1
type: youtube
video_id: z3fRu9pkuXE
id: 0
product_id: 0
length: string
required: false
responses:
'200':
description: ''
content:
application/json:
schema:
title: Update Products (Batch) Success Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/product_Full'
meta:
$ref: '#/components/schemas/metaCollection_Full'
examples:
example-1:
value:
data:
- id: 1
name: Smith Journal 13
type: physical
sku: SM-13
description: >-
<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: 0
width: 0
depth: 0
height: 0
price: 0
cost_price: 0
retail_price: 0
sale_price: 0
map_price: 0
tax_class_id: 0
product_tax_code: string
categories:
- 0
brand_id: 0
inventory_level: 0
inventory_warning_level: 0
inventory_tracking: none
fixed_cost_shipping_price: 0
is_free_shipping: true
is_visible: true
is_featured: true
related_products:
- 0
warranty: string
bin_picking_number: string
layout_file: string
upc: string
search_keywords: string
availability: available
availability_description: string
gift_wrapping_options_type: any
gift_wrapping_options_list:
- 0
sort_order: -2147483648
condition: New
is_condition_shown: true
order_quantity_minimum: 0
order_quantity_maximum: 0
page_title: string
meta_keywords:
- string
meta_description: string
view_count: 0
preorder_release_date: '2019-08-24T14:15:22Z'
preorder_message: string
is_preorder_only: true
is_price_hidden: true
price_hidden_label: string
custom_url:
url: string
is_customized: true
open_graph_type: product
open_graph_title: string
open_graph_description: string
open_graph_use_meta_description: true
open_graph_use_product_name: true
open_graph_use_image: true
brand_name: Common Good
gtin: string
mpn: string
date_last_imported: '2015-07-03T18:16:02+00:00'
reviews_rating_sum: 3
reviews_count: 4
total_sold: 80
custom_fields:
- id: 6
name: ISBN
value: '1234567890123'
bulk_pricing_rules:
- id: 0
quantity_min: 10
quantity_max: 50
type: price
amount: 10
images:
- image_file: string
is_thumbnail: true
sort_order: -2147483648
description: string
image_url: string
id: 0
product_id: 0
url_zoom: string
url_standard: string
url_thumbnail: string
url_tiny: string
date_modified: '2019-08-24T14:15:22Z'
videos:
- title: Writing Great Documentation
description: A video about documentation
sort_order: 1
type: youtube
video_id: z3fRu9pkuXE
id: 0
product_id: 0
length: string
date_created: '2018-08-15T14:49:05+00:00'
date_modified: '2018-08-24T14:41:00+00:00'
base_variant_id: 0
calculated_price: 0
options:
- id: 55
product_id: 4
display_name: Add-a-$5-Donation1535042499-187
type: radio_buttons
config:
default_value: string
checked_by_default: true
checkbox_label: string
date_limited: true
date_limit_mode: range
date_earliest_value: '2019-08-24'
date_latest_value: '2019-08-24'
file_types_mode: specific
file_types_supported:
- images, documents, other
file_types_other:
- pdf
file_max_size: 5
text_characters_limited: true
text_min_length: 1
text_max_length: 55
text_lines_limited: true
text_max_lines: 4
number_limited: true
number_limit_mode: lowest
number_lowest_value: 100
number_highest_value: 0
number_integers_only: false
product_list_adjusts_inventory: true
product_list_adjusts_pricing: true
product_list_shipping_calc: weight
sort_order: 1
option_values:
- is_default: false
label: Green
sort_order: 0
value_data: {}
id: 0
modifiers:
- type: date
required: true
sort_order: 0
config:
default_value: string
checked_by_default: true
checkbox_label: string
date_limited: true
date_limit_mode: range
date_earliest_value: '2019-08-24'
date_latest_value: '2019-08-24'
file_types_mode: specific
file_types_supported:
- images, documents, other
file_types_other:
- pdf
file_max_size: 5
text_characters_limited: true
text_min_length: 1
text_max_length: 55
text_lines_limited: true
text_max_lines: 4
number_limited: true
number_limit_mode: lowest
number_lowest_value: 100
number_highest_value: 0
number_integers_only: false
product_list_adjusts_inventory: true
product_list_adjusts_pricing: true
product_list_shipping_calc: weight
display_name: string
id: 12
product_id: 77
name: Add-a-$5-Donation1535039590-191
option_values:
- is_default: false
label: Green
sort_order: 0
value_data: {}
adjusters:
price:
adjuster: relative
adjuster_value: 5
weight:
adjuster: relative
adjuster_value: 5
image_url: >-
https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2
purchasing_disabled:
status: true
message: string
id: 0
option_id: 0
option_set_id: 0
option_set_display: string
variants:
- cost_price: 0
price: 0
sale_price: 0
retail_price: 0
weight: 0
width: 0
height: 0
depth: 0
is_free_shipping: true
fixed_cost_shipping_price: 0
purchasing_disabled: true
purchasing_disabled_message: string
upc: string
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: string
mpn: string
gtin: '012345678905'
id: 0
# --- truncated at 32 KB (376 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/catalog-products-openapi-original.yml