Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: BigCommerce Catalog - Product Variants Variants (Batch) API
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).\n\nA 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_.\n\nOur Catalog Product Variants endpoints let you work in two ways. \n\nOn 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.\n\nBy design, Product Variants consist of a combination of [Product Variant Option values](/docs/rest-catalog/product-variant-options/values).\n\nThis 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).\n\nThe terms \"product variant\" and \"variant\" are used interchangeably throughout the documentation.\n\n> To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**.\n\n## Resources\n\n### Webhooks\nLearn more about [Product webhook events](/docs/integrations/webhooks/events#products).\n\n### Additional Catalog endpoints\n* [Brands](/docs/rest-catalog/brands)\n* [Categories](/docs/rest-catalog/categories)\n* [Category Trees](/docs/rest-catalog/category-trees)\n* [Products](/docs/rest-catalog/products)\n* [Product Modifiers](/docs/rest-catalog/product-modifiers)\n* [Product Variant Options](/docs/rest-catalog/product-variant-options)"
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: support@bigcommerce.com
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: Variants (Batch)
paths:
/catalog/variants:
parameters:
- $ref: '#/components/parameters/Accept'
get:
tags:
- Variants (Batch)
summary: BigCommerce Get All Variants
description: Returns a list of all variants in your catalog. Optional parameters can be passed in.
operationId: getVariants
parameters:
- name: id
in: query
description: Filter items by ID.
schema:
type: integer
- name: sku
in: query
description: Filter items by SKU.
schema:
type: string
- name: upc
in: query
description: Filter items by UPC.
schema:
type: string
- 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
- name: product_id
in: query
description: A comma-separated list of IDs of products whose variants were requested. For example:`?product_id:in=77,80,81`
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Collection Response
type: object
properties:
data:
type: array
items:
type: object
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
x-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
x-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
x-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
x-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
x-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
x-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
x-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
x-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
x-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.
x-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). "
x-nullable: true
maximum: 2147483647
inventory_warning_level:
type: integer
description: When the variant hits this inventory level, it is considered low stock.
x-nullable: true
maximum: 2147483647
bin_picking_number:
maxLength: 255
minLength: 0
type: string
description: Identifies where in a warehouse the variant is located.
x-nullable: true
description: Common Variant properties.
- type: object
properties:
id:
type: integer
product_id:
type: integer
sku:
type: string
sku_id:
type: integer
description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
x-nullable: true
option_values:
type: array
description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.
items:
title: Option Value Variant
type: object
allOf:
- title: Option Value Product Base
type: object
properties:
option_display_name:
maxLength: 255
minLength: 1
type: string
description: 'The name of the option.
'
example: Color
x-required:
- post
label:
maxLength: 255
minLength: 1
type: string
description: 'The label of the option value.
'
example: Beige
x-required:
- post
description: Common Option Value Product properties.
- type: object
properties:
id:
type: integer
option_id:
type: integer
calculated_price:
type: number
description: 'The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant.
'
format: double
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.
put:
tags:
- Variants (Batch)
summary: BigCommerce Update Variants (Batch)
description: "Updates a batch of `variant` objects. Currently the limit is 50 variants however this is subject to change.\n\n**Required Fields**\n\nTo update an existing variant:\n* id (variant ID)\n\nTo create a new variant:\n* product_id\n* sku\n* option_values\n - id (option_value ID - Example: 146)\n - option_id (Option ID - Example: 151)"
operationId: updateVariantsBatch
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
title: Variants Collection Put
type: array
items:
title: Variant Put
type: object
description: 'The model for a PUT to update 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
x-nullable: true
example: 40
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
x-nullable: true
example: 40
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
x-nullable: true
example: 40
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
x-nullable: true
example: 40
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
x-nullable: true
example: 5
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
x-nullable: true
example: 5
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
x-nullable: true
example: 5
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
x-nullable: true
example: 5
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
x-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.
x-nullable: true
example: '1234'
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). "
x-nullable: true
maximum: 2147483647
example: 21474
inventory_warning_level:
type: integer
description: When the variant hits this inventory level, it is considered low stock.
x-nullable: true
maximum: 2147483647
example: 5474
bin_picking_number:
maxLength: 255
minLength: 0
type: string
description: Identifies where in a warehouse the variant is located.
x-nullable: true
description: Common Variant properties.
- type: object
properties:
id:
type: integer
example: 154
x-required:
- put
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Variant Collection Response
type: object
properties:
data:
type: array
items:
type: object
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
x-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
x-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
x-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
x-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
x-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
x-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
x-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
x-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
x-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.
x-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). "
x-nullable: true
maximum: 2147483647
inventory_warning_level:
type: integer
description: When the variant hits this inventory level, it is considered low stock.
x-nullable: true
maximum: 2147483647
bin_picking_number:
maxLength: 255
minLength: 0
type: string
description: Identifies where in a warehouse the variant is located.
x-nullable: true
description: Common Variant properties.
- type: object
properties:
id:
type: integer
product_id:
type: integer
sku:
type: string
sku_id:
type: integer
description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
x-nullable: true
option_values:
type: array
description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.
items:
title: Option Value Variant
type: object
allOf:
- title: Option Value Product Base
type: object
properties:
option_display_name:
maxLength: 255
minLength: 1
type: string
description: 'The name of the option.
'
example: Color
x-required:
- post
label:
maxLength: 255
minLength: 1
type: string
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-variants-batch-api-openapi.yml