openapi: 3.0.0
info:
title: BigCommerce Abandoned Cart Emails Product Variants 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: Product Variants
paths:
/catalog/products/{product_id}/variants:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
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. \n\nVerify 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
/catalog/products/{product_id}/variants/{variant_id}:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
- $ref: '#/components/parameters/VariantIdParam'
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. \n\nVerify 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: {}
components:
parameters:
Accept:
name: Accept
in: header
required: true
description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
schema:
type: string
default: application/json
ProductIdParam:
name: product_id
in: path
description: 'The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the `product_id` in the request path are successful as long as the parameter is not empty. The `product_id` segment is there only for path consistency.
'
required: true
schema:
type: integer
ContentType:
name: Content-Type
in: header
required: true
description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
schema:
type: string
default: application/json
VariantIdParam:
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
schemas:
productVariant_Base:
title: productVariant_Base
type: object
properties:
cost_price:
minimum: 0
type: number
description: The cost price of the variant. Not affected by Price List prices.
format: double
nullable: true
price:
minimum: 0
type: number
description: This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.
format: double
nullable: true
sale_price:
minimum: 0
type: number
description: This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.
format: double
nullable: true
retail_price:
minimum: 0
type: number
description: This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.
format: double
nullable: true
weight:
minimum: 0
type: number
description: This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
format: double
nullable: true
width:
minimum: 0
type: number
description: 'Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
'
format: double
nullable: true
height:
minimum: 0
type: number
description: 'Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
'
format: double
nullable: true
depth:
minimum: 0
type: number
description: 'Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
'
format: double
nullable: true
is_free_shipping:
type: boolean
description: 'Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero.
'
fixed_cost_shipping_price:
minimum: 0
type: number
description: 'A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
'
format: double
nullable: true
purchasing_disabled:
type: boolean
description: If `true`, this variant will not be purchasable on the storefront.
purchasing_disabled_message:
maxLength: 255
minLength: 0
type: string
description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
upc:
type: string
description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
nullable: true
inventory_level:
type: integer
description: "Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location.\n\nThe inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. \n\nIf you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.\n\nThe Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). "
nullable: true
maximum: 2147483647
inventory_warning_level:
type: integer
description: When the variant hits this inventory level, it is considered low stock.
nullable: true
maximum: 2147483647
bin_picking_number:
maxLength: 255
minLength: 0
type: string
description: Identifies where in a warehouse the variant is located.
nullable: true
mpn:
type: string
description: The Manufacturer Part Number (MPN) for the variant.
gtin:
type: string
example: 012345678905
description: Common Variant properties.
x-internal: false
x-examples:
example-1:
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
errorMultiStatus:
title: errorMultiStatus
type: object
properties:
status:
type: integer
minLength: 3
maxLength: 3
description: The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) of the failure or partial success.
title:
type: string
description: A summary of the failure or partial success.
type:
type: string
description: A BigCommerce-defined error signifier.
errors:
$ref: '#/components/schemas/DetailedErrors'
productVariant_Put:
title: productVariant_Put
description: The model for a PUT to update variants on a product.
allOf:
- $ref: '#/components/schemas/productVariant_Base'
- type: object
properties:
product_id:
type: integer
x-required:
- post
sku:
maxLength: 255
minLength: 1
type: string
x-required:
- post
x-internal: false
MultiStatus:
type: object
properties:
data:
$ref: '#/components/schemas/productVariant_Full'
errors:
$ref: '#/components/schemas/errorMultiStatus'
meta:
$ref: '#/components/schemas/metaCollection_Full'
productVariantOptionValue_Base:
title: productVariantOptionValue_Base
type: object
properties:
id:
type: integer
description: '`option_value` ID.'
example: 146
option_id:
type: integer
description: '`option` ID.'
example: 151
description: Common Product Variant Option properties.
x-internal: false
metaEmpty_Full:
type: object
title: Response meta
properties: {}
additionalProperties: true
description: Response metadata.
productVariant_Post:
title: productVariant_Post
description: 'The model for a POST to create variants on a product.
'
allOf:
- title: Variant Base
type: object
properties:
cost_price:
minimum: 0
type: number
description: The cost price of the variant. Not affected by Price List prices.
format: double
nullable: true
price:
minimum: 0
type: number
description: This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.
format: double
nullable: true
sale_price:
minimum: 0
type: number
description: This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.
format: double
nullable: true
retail_price:
minimum: 0
type: number
description: This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.
format: double
nullable: true
weight:
minimum: 0
type: number
description: This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
format: double
nullable: true
width:
minimum: 0
type: number
description: 'Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
'
format: double
nullable: true
height:
minimum: 0
type: number
description: 'Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
'
format: double
nullable: true
depth:
minimum: 0
type: number
description: 'Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
'
format: double
nullable: true
is_free_shipping:
type: boolean
description: 'Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero.
'
fixed_cost_shipping_price:
minimum: 0
type: number
description: 'A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
'
format: double
nullable: true
purchasing_disabled:
type: boolean
description: If `true`, this variant will not be purchasable on the storefront.
purchasing_disabled_message:
maxLength: 255
minLength: 0
type: string
description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
upc:
type: string
description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
nullable: true
inventory_level:
type: integer
description: "Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location.\n\nThe inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. \n\nIf you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.\n\nThe Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). "
nullable: true
maximum: 2147483647
inventory_warning_level:
type: integer
description: When the variant hits this inventory level, it is considered low sto
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-product-variants-api-openapi.yml