V2 versus V3 API
Advantages of V3 over V2
The V3 API introduces a number of improvements designed to improve efficiency. Most tasks can be performed with fewer API calls, and the V3 API supports the inclusion of subresources within a request. For example, you can now create a product with variants and custom fields in a single API call.
Each V3 resource includes a meta
object at the end of the response, making pagination easier.
Additionally, metafields have been added to the V3 Products resource so data can be stored against the object. Metafield values can be specific to your application or visible to other applications.
Lastly, the V3 API has been optimized for performance, allowing data to be synced quickly.
Products in V3
Variants
Every purchasable entity in the catalog is now a variant, including the product itself. This enables enhanced flows around inventory management, such as the ability to solely use the variants endpoint to manage inventory levels. For more on variants see Variants.
In V3 a variant needs to be created for every combination of option values. In V2 it was possible to create a SKU with a subset of product options.
We recommend creating products using V3 as BigCommerce starts to move operations to the V3 API.
Options and Modifiers
There is now a clear separation of options that define variants versus options that are modifiers of a variant. This simplifies the creation and management of variant prices and modifier adjusters and removes the need to use complex rules, in all but the most extreme cases.
In V3, options and modifiers are attached directly to the product, without the requirement to create an option set beforehand.
Creating Options on V2 has several steps:
- Create the product
- Create the options
- Create an option set
- Assign the option set to the product
- Create adjustments, such as price adjustment, using rules
Creating Products and Variants on V3:
- Create the product with variants in one call
- Create adjustments, such as price adjustment, directly on the variant or modifier
Variants can be included with a GET request to lower the number of API calls being made using ?include=variants
.
V3 includes endpoints for working with catalog trees. Stores that have multi-storefront enabled can have more than one tree. See the categories section of the Multi-Storefront API Guide. Stores that are not MSF-enabled can use the same endponts.
Interoperability between V2 and V3
Previously (prior to December 17th, 2018), when a product option, is created in V2 and assigned to a product, trying to edit the global option using the V3 API would return a 422 error.
{
"status": 422,
"title": "The product is currently associated with an option set, please remove it before editing an option or modifier.",
"type": "/docs/start/about/status-codes",
"errors": {
"product_id": "The product is currently associated with an option set, please remove it before editing an option or modifier."
}
}
Instead of a 422 error, now it will automatically copy the V2 global product option to a local product variant option or modifier option. This is triggered by an Update or Delete to either the Product Variant Options or Product Modifiers endpoints.
What this does is:
- Changes the
option_value
>id
. Not theoption_id
. - Creates a copy directly on the product.
- Copies over any variants, modifiers and option set rules.
- In the Control Panel the product is listed as having a (Custom) Option Set.
- Global Option Set rules are copied as product rules and the
sort_order
is updated so they executed before any existing product rules (which should mirror the behavior before the product was changed).
What this does not do:
- Remove the Option Set from the store entirely. It is still available in the control panel as an option set to be assigned.
- Change product pricing, rules or any other product modifiers. They will be copied over and assigned the product correctly.
Update Request to Product Option Values
On the following product, you will see the original option response of a product created using V2, a change to the option values and then the final option response.
This product is a T-Shirt with a global option set of size and color added. Take a note of the option values id’s. These will change when an update is made to the option using the /options endpoint on V3. While they will all change since the entire option set is copied to the product, the one we are updating below is the label for Size Small, which has a option_value
> id
of 192.
// Note the option_values id's for the colors are 180, 181 and 182. The values for color are 192, 193 and 194.
{
"data": [
{
"id": 242,
"product_id": 201,
"name": "Color",
"display_name": "Color",
"type": "swatch",
"sort_order": 0,
"option_values": [
{
"id": 180,
"label": "Red",
"sort_order": 1,
"value_data": {
"colors": [
"#ff0000"
]
},
"is_default": false
},
{
"id": 181,
"label": "Green",
"sort_order": 2,
"value_data": {
"colors": [
"#008000"
]
},
"is_default": false
},
{
"id": 182,
"label": "Blue",
"sort_order": 3,
"value_data": {
"colors": [
"#0000ff"
]
},
"is_default": false
}
],
"config": []
},
{
"id": 243,
"product_id": 201,
"name": "Size",
"display_name": "T-Shirt Size",
"type": "rectangles",
"sort_order": 1,
"option_values": [
{
"id": 192,
"label": "Small",
"sort_order": 0,
"value_data": null,
"is_default": false
},
{
"id": 193,
"label": "Medium",
"sort_order": 1,
"value_data": null,
"is_default": false
},
{
"id": 194,
"label": "Large",
"sort_order": 2,
"value_data": null,
"is_default": false
}
],
"config": []
}
],
"meta": {
"pagination": {
"total": 2,
"count": 2,
"per_page": 50,
"current_page": 1,
"total_pages": 1,
"links": {
"current": "?page=1&limit=50"
}
}
}
}
Below, "Small" is updated to "Small T-Shirt".
{
"label": "Small T-Shirt"
}
{
"data": {
"id": 214,
"label": "Small T-Shirt",
"sort_order": 0,
"value_data": null,
"is_default": false
},
"meta": {}
}
The ID is now 214. It was changed from 192. Below you can see the option_value
> id
for all the options changed even though only one was edited. The Control Panel now shows the options as (Custom).
// The option_value > id is now 214
{
"data": [
{
"id": 242,
"product_id": 201,
"name": "Color1545071633-201",
"display_name": "Color",
"type": "swatch",
"sort_order": 0,
"option_values": [
{
"id": 211,
"label": "Red",
"sort_order": 1,
"value_data": {
"colors": [
"#ff0000"
]
},
"is_default": false
},
{
"id": 212,
"label": "Green",
"sort_order": 2,
"value_data": {
"colors": [
"#008000"
]
},
"is_default": false
},
{
"id": 213,
"label": "Blue",
"sort_order": 3,
"value_data": {
"colors": [
"#0000ff"
]
},
"is_default": false
}
],
"config": []
},
{
"id": 243,
"product_id": 201,
"name": "T-Shirt-Size1545071633-201",
"display_name": "T-Shirt Size",
"type": "rectangles",
"sort_order": 1,
"option_values": [
{
"id": 214,
"label": "Small T-Shirt",
"sort_order": 0,
"value_data": null,
"is_default": false
},
{
"id": 215,
"label": "Medium",
"sort_order": 1,
"value_data": null,
"is_default": false
},
{
"id": 216,
"label": "Large",
"sort_order": 2,
"value_data": null,
"is_default": false
}
],
"config": []
}
],
"meta": {
"pagination": {
"total": 2,
"count": 2,
"per_page": 50,
"current_page": 1,
"total_pages": 1,
"links": {
"current": "?page=1&limit=50"
}
}
}
}
What's not in V3
In V3, options are attached directly to products. So option sets are not required, and V3 includes no endpoint to manage option sets. However, V3 will respect option sets that have been attached via V2 or the control panel.
Moving forward, new resources will be built in V3 and existing V2 resources will eventually be migrated to V3. Some V3 resources do not have V2 counterparts, and vice versa.
Complex Rules
Most of the use cases for using V2 rules can be solved by making adjustments directly on variants and modifier options. We recommend using variants as best practice, but in cases where an adjustment depends on the selection of multiple modifier values, V3 includes a Complex Rules resource.
Product Rules
Any variant created in v3 with non-null core properties (price, weight, image, purchasability) will create a rule under the hood. The same goes for modifier adjusters. These will show in v2 as product rules, and any edits to them will be shared across API versions.
Option Sets
In our control panel’s Add/Edit Product section, any products created by the V3 API will not have an option set applied, but merchants can still edit the options. If the merchant applies an option set to a V3 product, the product's variants will be removed. Currently, the Add/Edit Product area consumes the V2 API, so products created and managed through the control panel will be converted to the V2 model, using option sets.
Recommendations
When the resource is available in V3, it is best practice to use the V3 endpoint. For resources that do not have a V3 counterpart, like Orders, use V2. Both the V2 and V3 APIs authenticate with Oauth and are designed to be used concurrently within a single application.
We have created a handy cheat sheet below that lists all the differences between V2 and V3 of the API.
V2 and V3 Cheat Sheet
This identifies the differences between major actions on both versions.
In the examples below:
- Simple product is defined as not having variants, modifiers or options.
- Complex Products are defined as having variants, options and modifiers.
Simple Product
Get a Product
Response V3 Product
GET /v3/catalog/products/{product_id}
{
"data": {
"id": 195,
"name": "BigCommerce Coffee Mug_3",
"type": "physical",
"sku": "",
"description": "",
"weight": 3,
"width": 0,
"depth": 0,
"height": 0,
"price": 11,
"cost_price": 0,
"retail_price": 0,
"sale_price": 0,
"map_price": 0,
"tax_class_id": 0,
"product_tax_code": "",
"calculated_price": 11,
"categories": [
21
],
"brand_id": 38,
"option_set_id": 50,
"option_set_display": "right",
"inventory_level": 400,
"inventory_warning_level": 40,
"inventory_tracking": "variant",
"reviews_rating_sum": 0,
"reviews_count": 0,
"total_sold": 0,
"fixed_cost_shipping_price": 0,
"is_free_shipping": false,
"is_visible": true,
"is_featured": false,
"related_products": [
-1
],
"warranty": "",
"bin_picking_number": "",
"layout_file": "product.html",
"upc": "",
"mpn": "",
"gtin": "",
"search_keywords": "",
"availability": "available",
"availability_description": "",
"gift_wrapping_options_type": "any",
"gift_wrapping_options_list": [],
"sort_order": 0,
"condition": "New",
"is_condition_shown": false,
"order_quantity_minimum": 0,
"order_quantity_maximum": 0,
"page_title": "",
"meta_keywords": [],
"meta_description": "",
"date_created": "2018-09-05T20:22:19+00:00",
"date_modified": "2018-09-20T15:28:50+00:00",
"view_count": 4,
"preorder_release_date": null,
"preorder_message": "",
"is_preorder_only": false,
"is_price_hidden": false,
"price_hidden_label": "",
"custom_url": {
"url": "/bigcommerce-coffee-mug_3/",
"is_customized": false
},
"base_variant_id": null,
"open_graph_type": "product",
"open_graph_title": "",
"open_graph_description": "",
"open_graph_use_meta_description": true,
"open_graph_use_product_name": true,
"open_graph_use_image": true
},
"meta": {}
}
Response V2 Product
GET /v2/products/{product_id}
{
"id": 195,
"keyword_filter": null,
"name": "BigCommerce Coffee Mug_3",
"type": "physical",
"sku": "",
"description": "",
"search_keywords": "",
"availability_description": "",
"price": "11.0000",
"cost_price": "0.0000",
"retail_price": "0.0000",
"sale_price": "0.0000",
"calculated_price": "11.0000",
"sort_order": 0,
"is_visible": true,
"is_featured": false,
"related_products": "-1",
"inventory_level": 400,
"inventory_warning_level": 40,
"warranty": "",
"weight": "3.0000",
"width": "0.0000",
"height": "0.0000",
"depth": "0.0000",
"fixed_cost_shipping_price": "0.0000",
"is_free_shipping": false,
"inventory_tracking": "sku",
"rating_total": 0,
"rating_count": 0,
"total_sold": 0,
"date_created": "Wed, 05 Sep 2018 20:22:19 +0000",
"brand_id": 38,
"view_count": 4,
"page_title": "",
"meta_keywords": "",
"meta_description": "",
"layout_file": "product.html",
"is_price_hidden": false,
"price_hidden_label": "",
"categories": [
21
],
"date_modified": "Thu, 20 Sep 2018 15:28:50 +0000",
"event_date_field_name": "",
"event_date_type": "none",
"event_date_start": null,
"event_date_end": null,
"myob_asset_account": "",
"myob_income_account": "",
"myob_expense_account": "",
"peachtree_gl_account": "",
"condition": "New",
"is_condition_shown": false,
"preorder_release_date": "",
"is_preorder_only": false,
"preorder_message": "",
"order_quantity_minimum": 0,
"order_quantity_maximum": 0,
"open_graph_type": "product",
"open_graph_title": "",
"open_graph_description": "",
"is_open_graph_thumbnail": true,
"upc": "",
"avalara_product_tax_code": "",
"date_last_imported": "",
"option_set_id": 50,
"tax_class_id": 0,
"option_set_display": "right",
"bin_picking_number": "",
"custom_url": "/bigcommerce-coffee-mug_3/",
"primary_image": {
"id": 0,
"zoom_url": null,
"thumbnail_url": null,
"standard_url": null,
"tiny_url": null
},
"availability": "available",
"brand": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/brands/38",
"resource": "/brands/38"
},
"downloads": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/downloads",
"resource": "/products/195/downloads"
},
"images": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/images",
"resource": "/products/195/images"
},
"discount_rules": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/discountrules",
"resource": "/products/195/discountrules"
},
"configurable_fields": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/configurablefields",
"resource": "/products/195/configurablefields"
},
"custom_fields": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/customfields",
"resource": "/products/195/customfields"
},
"videos": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/videos",
"resource": "/products/195/videos"
},
"skus": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/skus",
"resource": "/products/195/skus"
},
"rules": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/rules",
"resource": "/products/195/rules"
},
"option_set": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/optionsets/50",
"resource": "/optionsets/50"
},
"options": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/options",
"resource": "/products/195/options"
},
"tax_class": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/taxclasses/0",
"resource": "/taxclasses/0"
},
"reviews": {
"url": "https://api.bigcommerce.com/stores/id30h7ohwf/v2/products/195/reviews",
"resource": "/products/195/reviews"
},
"metadata": []
}
Create a Product
Request V3 Product
POST /v3/catalog/products
{
"name": "BigCommerce Coffee Mug",
"price": "10.00",
"categories": [
23,
21
],
"weight": 4,
"type": "physical"
}
Request V2 Product
POST /v2/products
{
"name": "Plain T-Shirt",
"type": "physical",
"description": "This timeless fashion staple will never go out of style!",
"price": "29.99",
"categories": [
18
],
"availability": "available",
"weight": "0.5"
}
Create Product with Images
Request V3 Product Images
POST /v3/catalog/products/{product_id}/images
- Create a product using:
POST /v3/catalog/products
- Add images using:
POST /v3/catalog/products/{product_id}/images
{
"is_thumbnail": true,
"sort_order": 1,
"description": "Top View",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg"
}
Request V2 Product Images
POST /v2/products/{product_id}/images
- Create a product using:
POST /v2/products
- Add images using:
POST /v2/products/{product_id}/images
- Only accepts form data.
curl -X POST \
https://api.bigcommerce.com/stores/{store_hash}/v2/products/{product_id}/images \
-H 'Accept: application/json' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 841f5f9a-244b-4d2c-900f-938ac2067a4a' \
-H 'X-Auth-Token: {X-Auth-Token}' \
-H 'content-type: multipart/form-data; boundary=-WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F image_file=@/Users/{user_name}/Documents/product_images/image_file.png
Create Product with Video
Request V3 Product Videos
POST /v3/catalog/products/{{id}}/videos
- Create a product using:
POST /v3/catalog/products
- Add video using:
POST /v3/catalog/products/{{id}}/videos
{
"title": "Your Video",
"description": "Company Values",
"sort_order": 1,
"type": "youtube",
"video_id": "123345AA"
}
Request V2 Product Videos
POST /v2/products/{{id}}/videos
{
"url": "https://www.youtube.com/watch?v=4wZ3ZG_Wams"
}
Complex Products
Create Product with Variants/SKU
Request V3 Product Variants
POST /v3/catalog/products
{
"name": "BigCommerce Coffee Mug",
"price": "10.00",
"categories": [
23,
21
],
"weight": 4,
"type": "physical",
"variants": [
{
"sku": "SKU-BLU",
"option_values": [
{
"option_display_name": "Mug Color",
"label": "Blue"
}
]
},
{
"sku": "SKU-GRAY",
"option_values": [
{
"option_display_name": "Mug Color",
"label": "Gray"
}
]
}
]
}
V2 Scenarios
When using the V2 Products API to make product options and option sets. The simplest workflow is when starting from scratch is below:
- Create an Option (in this example Size)
- Add option values
- Add the options created in step 1 to the option set
- Create an Option Set
- Add options created in step 1 and step 2 to the option set.
- Assign the option set to the product
- Assign SKU's to the Options on the product
Create an Option
POST /v2/option_sets
This will only create an option with no values added.
{
"name": "Size",
"display_name": "T-Shirt Size",
"type": "RT"
}
Add option values
POST /v2/options/{option_id}/values
This will add values such as small, medium and large. Only one value at a time can be created. In this example it will take 3 seperate /POST requests to create all sizes.
{
"label": "Medium",
"sort_order": 1,
"value": "Medium",
"is_default": false
}
After the option with values has been created, an option set needs to be created so the option and values created in the previous steps can be added to it.
Create Option Set
POST /v2/optionsets
{
"name": "T-Shirt Sizes BigCommerce"
}
Add the T-Shirt Size Options to Set
POST /optionsets/{option_set_id}/options
{
"option_id": 88
}
To assign the option set to a product, do a /PUT request against the product and update the option_set_id
field.
Assign the Option Set to the Product
PUT /v2/products/{product_id}*
{
"option_set_id": 60
}
To create the SKU's first you need the option_value_id
.
/GET optionsets/{option_set_id}/options
{
"id": 119,
"option_id": 88,
"option_set_id": 60,
"display_name": "T-Shirt Size",
"sort_order": 0,
"is_required": false,
"option": {
"url": "https://api.bigcommerce.com/stores/{store_hash}/v2/options/88",
"resource": "/options/88"
},
"values": [
{
"label": "Small",
"sort_order": 0,
"value": "Small",
"is_default": false,
"option_value_id": 192
},
{
"label": "Medium",
"sort_order": 1,
"value": "Medium",
"is_default": false,
"option_value_id": 193
},
{
"label": "Large",
"sort_order": 2,
"value": "Large",
"is_default": false,
"option_value_id": 194
}
]
}
The product_option_id
is also required.
/v2/products/{product_id}/options
.
Each size will need a separate POST to create all the SKU's.
Add Product SKU
POST /v2/products/{product_id}/skus
{
"sku": "SMALL-1",
"options": [
{
"product_option_id": 223,
"option_value_id": 192
}
]
}
Create a Product with Variants & Modifiers
Request V3 Modifier
POST /v3/catalog/products/{product_id}/modifiers
This examples uses a checkbox which is created in two steps.
- Create Modifier
{
"type": "checkbox",
"required": false,
"config": {
"default_value": "Yes",
"checked_by_default": false,
"checkbox_label": "Check for Donation"
},
"display_name": "Add a $5 Donation"
}
- Update Modifier Values
PUT /v3/catalog/products/{product_id}/modifiers/{modifier_id}/values
{
"is_default": false,
"adjusters": {
"price": {
"adjuster": "relative",
"adjuster_value": 5
}
}
}
V2 Modifier
- Modifiers are considered an option on V2. They can be assigned a SKU or not.
- They follow the same steps as Create Product with Variants/SKU
- Create an Option (in this example Size)
- Add option values
- Add the options created in step 1 to the option set
- Create an Option Set
- Add options created in step 1 and step 2 to the option set.
- Assign the option set to the product.
Create a Product with Rules/Complex Rules
POST /v3/catalog/products/{product_id}/complex-rules
They are not recommended for V3 products since they can be created at the variant level. See Complex Rules for more information.
{
"product_id": 1200,
"enabled": true,
"price_adjuster": {
"adjuster_value": 10
},
"conditions": [
{
"modifier_id": 506,
"modifier_value_id": 852
},
{
"modifier_id": 507,
"modifier_value_id": 854
}
]
}
Request V2 Product Rules
/v2/products/{product_id}/rules
- A complex rule can not be added without an option
The example below add's a complex rule to increase the price by $5 if the checkbox is selected.
{
"id": 89,
"product_id": null,
"name": "Checkbox",
"display_name": "$5 for Insurance",
"type": "C",
"values": {
"url": "https://api.bigcommerce.com/stores/{store_hash}/v2/options/89/values",
"resource": "/options/89/values"
}
}
{
"price_adjuster": {
"adjuster": "relative",
"adjuster_value": 5
},
"conditions": [
{
"product_option_id": 89,
"option_value_id": 195
}
]
}
Stock Levels
Update Stock Levels
For a simple product
Request V3 Product Stock
PUT /v3/catalog/products/{id}
{
"inventory_level": 100,
"inventory_warning_level": 10
}
Request V2 Product Stock
PUT /v2/products/{id}
{
"inventory_level": 15,
"inventory_warning_level": 5,
}
Update Stock Levels on Variant/SKU
For a single SKU
Request V3 Stock Variant
PUT /v3/catalog/products/{id}/variants/{id}
{
"inventory_level": 100,
"inventory_warning_level": 10
}
Request V2 Stock Variant
PUT /v2/products/{id}/skus/{id}
{
"inventory_level": 100,
"inventory_warning_level": 10,
"id": 388,
"sku": "SKU-4484A834"
}
Update Stock Levels on Multiple Variants/SKU
Request V3 Stock on Multiple Variants
PUT /v3/catalog/products/{id}
[
{
"inventory_level": 100,
"inventory_warning_level": 10,
"id": 388,
"sku": "SKU-4484A834"
},
{
"inventory_level": 100,
"inventory_warning_level": 10,
"id": 389,
"sku": "SKU-9E932372"
}
]
Request V2 Stock Level SKU
PUT /v2/products/{id}/skus/{id}
A request must be sent for each SKU
{
"inventory_level": 100,
"inventory_warning_level": 10
}