Update Product Variant

Updates a product variant.

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.

Path parameters

product_idstringRequired

variant_idstringRequired

Request

This endpoint expects an object.

bin_picking_numberstring or nullOptional0-255 characters

Identifies where in a warehouse the variant is located.

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.

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.

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.

gtinstring or nullOptional0-14 characters

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.

image_urlstringOptional

Publicly available image url

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 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](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api).

inventory_warning_levelinteger or nullOptional<=2147483647

When the variant hits this inventory level, it is considered low stock.

is_free_shippingbooleanOptional

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

mpnstring or nullOptional

The Manufacturer Part Number (MPN) for the variant.

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.

product_idintegerOptional

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.

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.

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.

skustringOptional1-255 characters

upcstring or nullOptional0-14 characters

The UPC code used in feeds for shopping comparison sites and external channel integrations.

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.

Response

dataobject

metaobject

Response metadata.

Errors

404

Not Found Error

1	import requests
2
3	url = "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/product_id/variants/variant_id"
4
5	payload = {}
6	headers = {
7	"X-Auth-Token": "<apiKey>",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.put(url, json=payload, headers=headers)
12
13	print(response.json())

1	{
2	"data": {
3	"bin_picking_number": "string",
4	"calculated_price": 1.1,
5	"calculated_weight": 1.1,
6	"cost_price": 1.1,
7	"depth": 1.1,
8	"fixed_cost_shipping_price": 1.1,
9	"gtin": "012345678905",
10	"height": 1.1,
11	"id": 1,
12	"image_url": "string",
13	"inventory_level": 1,
14	"inventory_warning_level": 1,
15	"is_free_shipping": true,
16	"mpn": "string",
17	"option_values": [
18	{
19	"id": 146,
20	"label": "Beige",
21	"option_display_name": "Color",
22	"option_id": 151
23	}
24	],
25	"price": 1.1,
26	"product_id": 1,
27	"purchasing_disabled": true,
28	"purchasing_disabled_message": "string",
29	"retail_price": 1.1,
30	"sale_price": 1.1,
31	"sku": "string",
32	"sku_id": 1,
33	"upc": "string",
34	"weight": 1.1,
35	"width": 1.1
36	},
37	"meta": {
38	"pagination": {
39	"total": 36,
40	"count": 36,
41	"per_page": 50,
42	"current_page": 1,
43	"total_pages": 1,
44	"links": {
45	"previous": "string",
46	"current": "?page=1&limit=50",
47	"next": "string"
48	}
49	}
50	},
51	"errors": {
52	"status": 1,
53	"title": "string",
54	"type": "string",
55	"errors": {}
56	}
57	}

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Request

Response

Errors

OAuth scopes

Authentication header

Further reading