> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Catalog - Product variants > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/developer/docs/admin/catalog-and-inventory). 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*. > **Info** > > A product's [`inventory_tracking`](/developer/api-reference/rest/admin/catalog/products/create-product#request.body.inventory_tracking) value also controls whether the storefront restricts option selection to combinations that exist as variants. Storefront option-availability filtering applies only when both of the following are true: > > * The store's out-of-stock option behavior (**Settings** > **Inventory**) is set to label or hide unavailable options, not to leave them selectable. See [BigCommerce Inventory Functionality (Help Center)](https://support.bigcommerce.com/s/article/BigCommerce-Inventory-Functionality?language=en_US). > * The product has `inventory_tracking: variant`. > > When the product uses `none` or `product` tracking, every option combination stays selectable regardless of which variants exist, so shoppers can select combinations that have no matching variant. Because the availability list is built only from combinations with stock greater than zero, enabling `variant` tracking to hide non-existent combinations also hides or labels real variants once they sell out. ## Base variant A base variant is a virtual projection of the parent product itself, exposed through the Variants API for consistency. When you update a base variant through the [Update a product variant](/developer/api-reference/rest/admin/catalog/product-variants/update-product-variant) or [Update variants (batch)](/developer/api-reference/rest/admin/catalog/product-variants/variants-batch/update-variants-batch) endpoint, the changes are applied to the underlying product. Only the following fields are propagated: `sku`, `price`, `weight`, `width`, `height`, `depth`, `is_free_shipping`, `fixed_cost_shipping_price`, `cost_price`, `sale_price`, `retail_price`, `upc`, `mpn`, `gtin`, `inventory_level`, `inventory_warning_level`, `bin_picking_number`, `purchasing_disabled`, `purchasing_disabled_message` > **Info** > > For all other product-level data — including images, descriptions, SEO fields, categories, custom fields, and metadata — use the [Products API](/developer/api-reference/rest/admin/catalog/products) directly. > > The Variants API for base variants exists primarily for backward compatibility and integration consistency, exposing only a limited subset of product fields. > > When a product has real variants (with options), base variant behavior no longer applies — each variant becomes a first-class entity. Our Catalog product variants endpoints let you work in two ways. On a per-product basis, you can [create and manage product variants](/developer/api-reference/rest/admin/catalog/product-variants), their [images](/developer/api-reference/rest/admin/catalog/product-variants/images), and their [metafields](/developer/api-reference/rest/admin/catalog/product-variants/metafields), which are arbitrary key-value attributes. By design, product variants consist of a combination of [product variant option values](/developer/api-reference/rest/admin/catalog/product-variant-options/values). This API family also provides endpoints that can make [batch updates](/developer/api-reference/rest/admin/catalog/product-variants/variants-batch/update-variants-batch) to product variants from different products across the Catalog, as well as [getting all variants](/developer/api-reference/rest/admin/catalog/product-variants/get-product-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](/developer/docs/integrations/webhooks/event-reference#products). ### Additional Catalog endpoints * [Brands](/developer/api-reference/rest/admin/catalog/brands) * [Categories](/developer/api-reference/rest/admin/catalog/categories) * [Category trees](/developer/api-reference/rest/admin/catalog/category-trees) * [Products](/developer/api-reference/rest/admin/catalog/products) * [Product modifiers](/developer/api-reference/rest/admin/catalog/product-modifiers) * [Product variant options](/developer/api-reference/rest/admin/catalog/product-variant-options) > Build amazing commerce solutions powered by the BigCommerce platform ## API Docs - Admin Catalog: Product Variants [List Product Variants](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/get-product-variants.md) - Admin Catalog: Product Variants [Create Product Variant](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/create-product-variant.md) - Admin Catalog: Product Variants [Get Product Variant](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/get-product-variant.md) - Admin Catalog: Product Variants [Update Product Variant](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/update-product-variant.md) - Admin Catalog: Product Variants [Delete Product Variant](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/delete-product-variant.md) - Admin Catalog: Product Variants > Batch Metafields [List Product Variant Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/batch-metafields/get-variants-metafields.md) - Admin Catalog: Product Variants > Batch Metafields [Create Multiple Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/batch-metafields/create-variants-metafields.md) - Admin Catalog: Product Variants > Batch Metafields [Update Multiple Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/batch-metafields/update-variants-metafields.md) - Admin Catalog: Product Variants > Batch Metafields [Delete Multiple Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/batch-metafields/delete-variants-metafields.md) - Admin Catalog: Product Variants > Images [Create Product Variant Image](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/images/create-product-variant-image.md) - Admin Catalog: Product Variants > Metafields [List Product Variant Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/metafields/get-product-variant-metafields.md) - Admin Catalog: Product Variants > Metafields [Create Product Variant Metafield](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/metafields/create-product-variant-metafield.md) - Admin Catalog: Product Variants > Metafields [Get Product Variant Metafield](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/metafields/get-product-variant-metafield.md) - Admin Catalog: Product Variants > Metafields [Update Product Variant Metafields](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/metafields/update-product-variant-metafield.md) - Admin Catalog: Product Variants > Metafields [Delete Product Variant Metafield](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/metafields/delete-product-variant-metafield.md) - Admin Catalog: Product Variants > Variants Batch [List Variants](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/variants-batch/get-variants.md) - Admin Catalog: Product Variants > Variants Batch [Update Variants (batch)](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/variants-batch/update-variants-batch.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/openapi.json) - [OpenAPI YAML](https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/openapi.yaml)