For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Brands
        • Categories
        • Category Trees
        • Products
        • Product Modifiers
        • Product Variants
            • GETList Product Variants
            • POSTCreate Product Variant
            • GETGet Product Variant
            • PUTUpdate Product Variant
            • DELDelete Product Variant
        • Product Variant Options
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminCatalogProduct Variants

Create Product Variant

POST
https://api.bigcommerce.com/stores/:store_hash/v3/catalog/products/:product_id/variants
POST
/stores/:store_hash/v3/catalog/products/:product_id/variants
$curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/variants \
>     -H "Accept: application/json" \
>     -H "X-Auth-Token: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{}'
1{
2  "data": {
3    "bin_picking_number": "A12-B34",
4    "calculated_price": 25,
5    "calculated_weight": 1,
6    "cost_price": 15,
7    "depth": 8,
8    "fixed_cost_shipping_price": 5,
9    "gtin": "012345678905",
10    "height": 5,
11    "id": 101,
12    "image_url": "https://cdn.example.com/images/product_variant_123.jpg",
13    "inventory_level": 150,
14    "inventory_warning_level": 10,
15    "is_free_shipping": false,
16    "mpn": "MPN-987654",
17    "option_values": [
18      {
19        "id": 146,
20        "label": "Red",
21        "option_display_name": "Color",
22        "option_id": 151
23      },
24      {
25        "id": 147,
26        "label": "42",
27        "option_display_name": "Size",
28        "option_id": 152
29      }
30    ],
31    "price": 30,
32    "product_id": 1,
33    "purchasing_disabled": false,
34    "purchasing_disabled_message": "",
35    "retail_price": 35,
36    "sale_price": 25,
37    "sku": "HTS-RED-42",
38    "sku_id": 202,
39    "upc": "123456789012",
40    "weight": 1,
41    "width": 10
42  },
43  "meta": {}
44}
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](/developer/api-reference/rest/admin/catalog/products/create-product) endpoint during the initial product creation. To obtain the `option_values` to include in this request, use the [Create a product variant option](/developer/api-reference/rest/admin/catalog/product-variant-options/create-product-variant-option) endpoint.
Was this page helpful?
Previous

List Product Variants

Next

Get Product Variant

Built with

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 endpoint during the initial product creation. To obtain the option_values to include in this request, use the Create a product variant option endpoint.

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

product_idintegerRequired

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.

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Request

This endpoint expects an object.
cost_pricedouble or nullOptional>=0

The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when cost_price equals zero.

pricedouble or nullOptional>=0

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.

sale_pricedouble or nullOptional>=0

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.

retail_pricedouble or nullOptional>=0

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.

weightdouble or nullOptional>=0

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.

widthdouble or nullOptional>=0

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.

heightdouble or nullOptional>=0

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.

depthdouble or nullOptional>=0

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.

is_free_shippingbooleanOptional

Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

fixed_cost_shipping_pricedouble or nullOptional>=0

A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

purchasing_disabledbooleanOptional

If true, this variant will not be purchasable on the storefront.

purchasing_disabled_messagestringOptional0-255 characters

If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

upcstring or nullOptional0-14 characters
The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_levelinteger or nullOptional<=2147483647

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.

The 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.

If 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.

The Catalog API handles limits in a different way than the Inventory API. For more information, see Limit handling.

inventory_warning_levelinteger or nullOptional<=2147483647
When the variant hits this inventory level, it is considered low stock.
bin_picking_numberstring or nullOptional0-255 characters
Identifies where in a warehouse the variant is located.
image_urlstringOptional
Publicly available image url
gtinstring or nullOptional0-14 characters
Global Trade Item Number
mpnstring or nullOptional
Manufacturer Part Number
product_idintegerOptional
skustringOptional1-255 characters
option_valueslist of objectsOptional

Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.

Response

dataobject
metaobject
Response metadata.

Errors

404
Not Found Error

OAuth scopes

UI NamePermissionParameter
Productsmodifystore_v2_products
Productsread-onlystore_v2_products_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

The MIME type of the response body.