openapi: 3.0.0
info:
title: BigCommerce Abandoned Cart Emails Products API
version: 3.0.0
termsOfService: https://www.bigcommerce.com/terms
description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: support@bigcommerce.com
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: Products
paths:
/catalog/products:
parameters:
- $ref: '#/components/parameters/Accept'
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.\n 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.\n\n**Note:** The following sub-resources include:\n * variants\n * images\n * custom_fields\n * bulk_pricing_rules\n * primary_image\n * modifiers\n * options\n * 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
product_id: 0
sku: string
sku_id: 0
option_values:
- option_display_name: Color
label: Beige
id: 146
option_id: 151
calculated_price: 0
calculated_weight: 0
meta:
pagination:
total: 36
count: 36
per_page: 50
current_page: 1
total_pages: 1
links:
previous: string
current: ?page=1&limit=50
next: string
'207':
description: "Multi-status. Typically indicates that a partial failure has occurred, such as when a POST or PUT request is successful, but saving one of the attributes has failed.\n\nFor example, the product information was updated successfully, but the inventory data failed to update or saving the URL failed. \n\nIf inventory data failed to update, verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again.\n\nIf the URL failed to update, check that the URL uses Latin letters, is no more than 255 characters, and is not taken by any other entity."
content:
application/json:
schema:
title: Update Products (Batch) Multi-status Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/product_Full'
errors:
$ref: '#/components/schemas/errorMultiStatus'
meta:
$ref: '#/components/schemas/metaCollection_Full'
'404':
description: The resource was not found.
content:
application/json:
schema:
title: Not Found
type: object
properties:
status:
type: integer
description: '404 HTTP status code.
'
title:
type: string
description: The error title describing the particular error.
type:
type: string
instance:
type: string
description: Error payload for the BigCommerce API.
'409':
description: '`Product` was in conflict with another product. This is the result of duplicate unique values such as name or SKU; a missing or invalid `category_id`, `brand_id`, or `tax_class id`; or a conflicting `bulk_pricing_rule`.'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse_409'
'413':
description: 413 Request Entity Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/error_Base'
example:
errors: {}
status: 413
title: The request payload is too large. The maximum items allowed in the array is 10.
type: /api-docs/getting-started/api-status-codes
'422':
description: '`Product` was not valid. This is the result of missing required fields or invalid data. See the response for more details.'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse_422'
x-codegen-request-body-name: products
post:
tags:
- Products
summary: BigCommerce Create a Product
description: '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`
**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](/docs/rest-catalog/products/videos#create-a-product-video) for information.'
operationId: createProduct
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_Base'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Product Response
type: object
properties:
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-products-api-openapi.yml