BigCommerce Catalog - Product Variants is a feature that allows online retailers to easily manage and display different versions or options of a product on their website. This tool enables merchants to create and track various product variants, such as different sizes, colors, or materials, all within a single product listing.
openapi: 3.0.3
info:
title: BigCommerce Catalog - Product Variants
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).
A Product Variant is a version of a product that has its own SKU. For
example, a catalog might model a particular style of high-top sneakers that
come in both red and blue as one product - high-tops - with two variants -
red and blue. From a storefront point of view, Product Variants are often
what shoppers seek. They are also the object that maps to SKUs and tracks
inventory. A Product with one only Variant is a _base variant_.
Our Catalog Product Variants endpoints let you work in two ways.
On a per-product basis, you can [create and manage Product
Variants](/docs/rest-catalog/product-variants), their
[images](/docs/rest-catalog/product-variants/images), and their
[metafields](/docs/rest-catalog/product-variants/metafields), which are
arbitrary key-value attributes.
By design, Product Variants consist of a combination of [Product Variant
Option values](/docs/rest-catalog/product-variant-options/values).
This API family also provides endpoints that can make [batch
updates](/docs/rest-catalog/product-variants/variants-batch#update-variants-batch)
to Product Variants from different products across the Catalog, as well as
[getting all
variants](/docs/rest-catalog/product-variants/variants-batch#get-all-variants).
The terms "product variant" and "variant" are used interchangeably
throughout the documentation.
> To learn more about authenticating Catalog endpoints, locate the
**Authentication** section at the top of each endpoint, then click **Show
Details**.
## Resources
### Webhooks
Learn more about [Product webhook
events](/docs/integrations/webhooks/events#products).
### Additional Catalog endpoints
* [Brands](/docs/rest-catalog/brands)
* [Categories](/docs/rest-catalog/categories)
* [Category Trees](/docs/rest-catalog/category-trees)
* [Products](/docs/rest-catalog/products)
* [Product Modifiers](/docs/rest-catalog/product-modifiers)
* [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: Images
- name: Metafields
- name: Product Variants
- name: Variants (Batch)
paths:
/catalog/products/{product_id}/variants:
get:
tags:
- Product Variants
summary: BigCommerce Get All Product Variants
description: >-
Returns a list of product *Variants*. Optional parameters can be passed
in.
operationId: getProductVariants
parameters:
- 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.
schema:
type: integer
- 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
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Collection Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/productVariant_Full'
meta:
$ref: '#/components/schemas/metaCollection_Full'
example:
data:
- id: 382
product_id: 192
sku: SMIT
sku_id: 348
price: 10
calculated_price: 10
sale_price: 8
retail_price: 10
map_price: {}
weight: 4
calculated_weight: 2
width: 5
height: 5
depth: 5
is_free_shipping: false
fixed_cost_shipping_price: 10
purchasing_disabled: false
purchasing_disabled_message: ''
image_url: ''
cost_price: 0
upc: ''
mpn: ''
gtin: ''
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: ''
option_values:
- id: 174
label: Beige
option_id: 220
option_display_name: Color
- id: 383
product_id: 192
sku: SMIT-1
sku_id: 349
price: 25
calculated_price: 25
sale_price: 20
retail_price: 25
map_price: {}
weight: 2
calculated_weight: 1
width: 5
height: 5
depth: 5
is_free_shipping: false
fixed_cost_shipping_price: 10
purchasing_disabled: false
purchasing_disabled_message: ''
image_url: ''
cost_price: 25
upc: ''
mpn: ''
gtin: ''
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: ''
option_values:
- id: 175
label: Grey
option_id: 220
option_display_name: Color
- id: 384
product_id: 192
sku: SMIT-2
sku_id: 350
price: 25
calculated_price: 25
sale_price: 20
retail_price: 25
map_price: {}
weight: 2
calculated_weight: 1
width: 5
height: 5
depth: 5
is_free_shipping: false
fixed_cost_shipping_price: 10
purchasing_disabled: false
purchasing_disabled_message: ''
image_url: ''
cost_price: 25
upc: ''
mpn: ''
gtin: ''
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: ''
option_values:
- id: 176
label: Black
option_id: 220
option_display_name: Color
meta:
pagination:
total: 3
count: 3
per_page: 50
current_page: 1
total_pages: 1
links:
current: '?page=1&limit=50'
'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.
post:
tags:
- Product Variants
summary: BigCommerce Create a Product Variant
description: >-
Creates a *Product Variant*.
**Required Fields**
* sku
* option_values
**Read-Only Fields**
* id
**Limits**
* 600 SKUs per product limit.
* 255 characters SKU length limit.
Variants need to be created one at a time using this endpoint. To use a
variant array, create products, and variants in the same call use the
[Create Products](/docs/rest-catalog/products#create-a-product) endpoint
during the initial product creation.
operationId: createProductVariant
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/productVariant_Post'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Response
type: object
properties:
data:
$ref: '#/components/schemas/productVariant_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
examples:
example-1:
value:
data:
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: {}
example-2:
value:
data:
id: 384
product_id: 192
sku: SMIT-2
sku_id: 350
price: 25
calculated_price: 25
sale_price: 20
retail_price: 25
map_price: {}
weight: 2
calculated_weight: 1
width: 5
height: 5
depth: 5
is_free_shipping: false
fixed_cost_shipping_price: 10
purchasing_disabled: false
purchasing_disabled_message: ''
image_url: ''
cost_price: 25
upc: ''
mpn: ''
gtin: ''
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: ''
option_values:
- id: 176
label: Black
option_id: 220
option_display_name: Color
meta: {}
'207':
description: >-
Multi-status. The product information was updated successfully, but
the 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.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiStatus'
'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.
x-codegen-request-body-name: Variant
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
/catalog/products/{product_id}/variants/{variant_id}:
get:
tags:
- Product Variants
summary: BigCommerce Get a Product Variant
description: >-
Returns a single product *Variant*. Optional parameters can be passed
in.
operationId: getProductVariant
parameters:
- 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
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Response
type: object
properties:
data:
$ref: '#/components/schemas/productVariant_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
example:
data:
id: 384
product_id: 192
sku: SMIT-2
sku_id: 350
price: 25
calculated_price: 25
sale_price: 20
retail_price: 25
map_price: {}
weight: 2
calculated_weight: 1
width: 5
height: 5
depth: 5
is_free_shipping: false
fixed_cost_shipping_price: 10
purchasing_disabled: false
purchasing_disabled_message: ''
image_url: ''
cost_price: 25
upc: ''
mpn: ''
gtin: ''
inventory_level: 0
inventory_warning_level: 0
bin_picking_number: ''
option_values:
- id: 176
label: Black
option_id: 220
option_display_name: Color
meta: {}
'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.
put:
tags:
- Product Variants
summary: BigCommerce Update a Product Variant
description: Updates a product *Variant*.
operationId: updateProductVariant
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/productVariant_Put'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Response
type: object
properties:
data:
$ref: '#/components/schemas/productVariant_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
example:
data:
bin_picking_number: '0'
calculated_price: 85
calculated_weight: 1
cost_price: 0
depth: 22
fixed_cost_shipping_price: 0
gtin: ''
height: 14.6
id: 65
inventory_level: 0
inventory_warning_level: 0
is_free_shipping: false
map_price: 0
mpn: TR-SML02
option_values: []
price: 89
product_id: 81
purchasing_disabled: true
purchasing_disabled_message: This item is not available.
retail_price: 89
sale_price: 85
sku: OTS
sku_id: 10
upc: ''
weight: 1
width: 2
meta: {}
'207':
description: >-
Multi-status. The product information was updated successfully, but
the 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.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiStatus'
'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.
x-codegen-request-body-name: Variant
delete:
tags:
- Product Variants
summary: BigCommerce Delete a Product Variant
description: Deletes a product *Variant*.
operationId: deleteProductVariant
responses:
'204':
description: ''
content: {}
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
- $ref: '#/components/parameters/VariantIdParam'
/catalog/products/{product_id}/variants/{variant_id}/metafields:
get:
tags:
- Metafields
summary: BigCommerce Get Product Variant Metafields
description: >-
Returns a list of product variant *Metafields*. Optional parameters can
be passed in.
operationId: getProductVariantMetafields
parameters:
- name: variant_id
in: path
description: >
ID of the variant on a product, or on an associated Price List
Record.
required: true
schema:
type: integer
- 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.
schema:
type: integer
- name: key
in: query
description: |
Filter based on a metafieldʼs key.
schema:
type: string
- name: namespace
in: query
description: Filter based on a metafieldʼs namespace.
schema:
type: string
- 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
responses:
'200':
description: ''
content:
application/json:
schema:
title: Meta Field Collection Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/metafield_Full'
meta:
$ref: '#/components/schemas/categoriesTree_Resp'
'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.
post:
tags:
- Metafields
summary: BigCommerce Create a Product Variant Metafield
description: >-
Creates a product variant *Metafield*.
**Required Fields:**
* permission_set
* namespace
* key
* value
**Read-Only Fields**
* id
**Note:** The maxiumum number of metafields allowed on each order,
product, category, variant, or brand is 250 per client ID. For more
information, see [Platform
Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in
the Help Center.
operationId: createProductVariantMetafield
parameters:
- $ref: '#/components/parameters/ContentType'
- name: variant_id
in: path
description: >
ID of the variant on a product, or on an associated Price List
Record.
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/metafield_Base'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Metafield Response
type: object
properties:
data:
$ref: '#/components/schemas/metafield_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
example:
data:
id: 4
key: location_id
value: Shelf 3, Bin 5
namespace: App Namespace
permission_set: app_only
resource_type: variant
resource_id: 137
description: Where products are located
date_created: '2021-08-06T19:15:35+00:00'
date_modified: '2021-08-06T19:15:35+00:00'
meta: {}
'409':
description: >
The `Metafield` was in conflict with another `Metafield`. This can
be the result of duplicate unique-key combinations of the appʼs
client id, namespace, key, resource_type, and resource_id.
content:
application/json:
schema:
title: Error Response
type: object
properties:
errors:
title: Detailed Errors
type: object
properties: {}
additionalProperties: true
instance:
type: string
status:
type: integer
description: |
The HTTP status code.
title:
type: string
description: |
The error title describing the particular error.
type:
type: string
'422':
description: >
The `Metafield` was not valid. This is the result of missing
required fields, or of invalid data. See the response for more
details.
content:
application/json:
schema:
title: Error Response
type: object
properties:
errors:
title: Detailed Errors
type: object
properties: {}
additionalProperties: true
instance:
type: string
status:
type: integer
description: |
The HTTP status code.
title:
type: string
description: |
The error title describing the particular error.
type:
type: string
x-codegen-request-body-name: Metafield
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
- $ref: '#/components/parameters/VariantIdParam'
/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}:
get:
tags:
- Metafields
summary: BigCommerce Get a Product Variant Metafields
description: >-
Returns a single product variant *Metafield*. Optional parameters can be
passed in.
operationId: getProductVariantMetafield
parameters:
- 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
responses:
'200':
description: ''
content:
application/json:
schema:
title: Metafield Response
type: object
properties:
data:
$ref: '#/components/schemas/metafield_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
example:
data:
id: 8
key: location_id
value: Shelf 3, Bin 5
namespace: Inventory Namespace
permission_set: read
resource_type: variant
resource_id: 158
description: Where products are located
date_created: '2018-09-13T16:42:37+00:00'
date_modified: '2018-09-13T16:42:37+00:00'
meta: {}
'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.
put:
tags:
- Metafields
summary: BigCommerce Update Product Variant Metafields
description: "Updates a product variant *Metafield*.\n\n**Required Fields:**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. "
operationId: updateProductVariantMetafield
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/metafield_Base'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Metafield Response
type: object
properties:
data:
$ref: '#/components/schemas/metafield_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
example:
data:
id: 8
key: location_id
value: Shelf 3, Bin 5
namespace: Inventory Namespace
permission_set: read
resource_type: variant
resource_id: 158
description: Where products are located
date_created: '2018-09-13T16:42:37+00:00'
date_modified: '2018-09-13T16:42:37+00:00'
meta: {}
'404':
description: |
The resource was not found.
content:
application/json:
schema:
title: Not
# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/catalog-product-variants-openapi-original.yml