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.

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

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": "/api-reference/rest/overview/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 the option_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.

1
// Note the option_values id's for the colors are 180, 181 and 182. The values for color are 192, 193 and 194.  
2
{
3
    "data": [
4
        {
5
            "id": 242,
6
            "product_id": 201,
7
            "name": "Color",
8
            "display_name": "Color",
9
            "type": "swatch",
10
            "sort_order": 0,
11
            "option_values": [
12
                {
13
                    "id": 180,
14
                    "label": "Red",
15
                    "sort_order": 1,
16
                    "value_data": {
17
                        "colors": [
18
                            "#ff0000"
19
                        ]
20
                    },
21
                    "is_default": false
22
                },
23
                {
24
                    "id": 181,
25
                    "label": "Green",
26
                    "sort_order": 2,
27
                    "value_data": {
28
                        "colors": [
29
                            "#008000"
30
                        ]
31
                    },
32
                    "is_default": false
33
                },
34
                {
35
                    "id": 182,
36
                    "label": "Blue",
37
                    "sort_order": 3,
38
                    "value_data": {
39
                        "colors": [
40
                            "#0000ff"
41
                        ]
42
                    },
43
                    "is_default": false
44
                }
45
            ],
46
            "config": []
47
        },
48
        {
49
            "id": 243,
50
            "product_id": 201,
51
            "name": "Size",
52
            "display_name": "T-Shirt Size",
53
            "type": "rectangles",
54
            "sort_order": 1,
55
            "option_values": [
56
                {
57
                    "id": 192,
58
                    "label": "Small",
59
                    "sort_order": 0,
60
                    "value_data": null,
61
                    "is_default": false
62
                },
63
                {
64
                    "id": 193,
65
                    "label": "Medium",
66
                    "sort_order": 1,
67
                    "value_data": null,
68
                    "is_default": false
69
                },
70
                {
71
                    "id": 194,
72
                    "label": "Large",
73
                    "sort_order": 2,
74
                    "value_data": null,
75
                    "is_default": false
76
                }
77
            ],
78
            "config": []
79
        }
80
    ],
81
    "meta": {
82
        "pagination": {
83
            "total": 2,
84
            "count": 2,
85
            "per_page": 50,
86
            "current_page": 1,
87
            "total_pages": 1,
88
            "links": {
89
                "current": "?page=1&limit=50"
90
            }
91
        }
92
    }
93
}

Below, “Small” is updated to “Small T-Shirt”.

1
{
2
	"label": "Small T-Shirt"
3
}

1
{
2
    "data": {
3
        "id": 214,
4
        "label": "Small T-Shirt",
5
        "sort_order": 0,
6
        "value_data": null,
7
        "is_default": false
8
    },
9
    "meta": {}
10
}

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

1
// The option_value > id is now 214
2
{
3
    "data": [
4
        {
5
            "id": 242,
6
            "product_id": 201,
7
            "name": "Color1545071633-201",
8
            "display_name": "Color",
9
            "type": "swatch",
10
            "sort_order": 0,
11
            "option_values": [
12
                {
13
                    "id": 211,
14
                    "label": "Red",
15
                    "sort_order": 1,
16
                    "value_data": {
17
                        "colors": [
18
                            "#ff0000"
19
                        ]
20
                    },
21
                    "is_default": false
22
                },
23
                {
24
                    "id": 212,
25
                    "label": "Green",
26
                    "sort_order": 2,
27
                    "value_data": {
28
                        "colors": [
29
                            "#008000"
30
                        ]
31
                    },
32
                    "is_default": false
33
                },
34
                {
35
                    "id": 213,
36
                    "label": "Blue",
37
                    "sort_order": 3,
38
                    "value_data": {
39
                        "colors": [
40
                            "#0000ff"
41
                        ]
42
                    },
43
                    "is_default": false
44
                }
45
            ],
46
            "config": []
47
        },
48
        {
49
            "id": 243,
50
            "product_id": 201,
51
            "name": "T-Shirt-Size1545071633-201",
52
            "display_name": "T-Shirt Size",
53
            "type": "rectangles",
54
            "sort_order": 1,
55
            "option_values": [
56
                {
57
                    "id": 214,
58
                    "label": "Small T-Shirt",
59
                    "sort_order": 0,
60
                    "value_data": null,
61
                    "is_default": false
62
                },
63
                {
64
                    "id": 215,
65
                    "label": "Medium",
66
                    "sort_order": 1,
67
                    "value_data": null,
68
                    "is_default": false
69
                },
70
                {
71
                    "id": 216,
72
                    "label": "Large",
73
                    "sort_order": 2,
74
                    "value_data": null,
75
                    "is_default": false
76
                }
77
            ],
78
            "config": []
79
        }
80
    ],
81
    "meta": {
82
        "pagination": {
83
            "total": 2,
84
            "count": 2,
85
            "per_page": 50,
86
            "current_page": 1,
87
            "total_pages": 1,
88
            "links": {
89
                "current": "?page=1&limit=50"
90
            }
91
        }
92
    }
93
}

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

{
  "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": {}
}

{
  "name": "BigCommerce Coffee Mug",
  "price": "10.00",
  "categories": [
    23,
    21
  ],
  "weight": 4,
  "type": "physical"
}

{
  "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"
}

{
  "title": "Your Video",
  "description": "Company Values",
  "sort_order": 1,
  "type": "youtube",
  "video_id": "123345AA"
}

Complex 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"
        }
      ]
    }
  ]
}

{
  "type": "checkbox",
  "required": false,
  "config": {
    "default_value": "Yes",
    "checked_by_default": false,
    "checkbox_label": "Check for Donation"
  },
  "display_name": "Add a $5 Donation"
}

{
  "is_default": false,
  "adjusters": {
    "price": {
      "adjuster": "relative",
      "adjuster_value": 5
    }
  }
}

{
  "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
    }
  ]
}

Stock Levels

{
  "inventory_level": 100,
  "inventory_warning_level": 10
}

{
  "inventory_level": 100,
  "inventory_warning_level": 10
}

[
  {
    "inventory_level": 100,
    "inventory_warning_level": 10,
    "id": 388,
    "sku": "SKU-4484A834"
  },
  {
    "inventory_level": 100,
    "inventory_warning_level": 10,
    "id": 389,
    "sku": "SKU-9E932372"
  }
]