NAV
  • Getting Started
  • Subscribe to developer updates

    Welcome to the v3 API

    Welcome to our v3 API, where we offer a more-efficient model for creating and handling product variants, options, and modifiers.
    This API is OAuth-only, but fully backward-compatible with our v2 API.

    Run Collection in Postman Want to jump right in and try it out? Import our collection of Postman requests, which address a growing subset of our v3 APIs. Learn how to authorize and use the collection here.
    Using the v3 API
    Covers authentication, new features, planned additions, interoperability with the v2 API and control panel, and usage examples.

    Using the v3 API

    Access the v3 YAML
    Directly access our public v3 API’s Swagger output, which you can plug into editor.swagger.io, ReDoc, or your favorite viewer or editor.

    Access v3 YAML

    Catalog API
    Features streamlined handling of variants, options, and modifiers, allowing apps to create a product along with its variants in a single API call.

    Catalog API

    Customers API
    Provides a new Newsletter Subscribers resource.



    Customers API

    Orders API
    Provides a new Transactions resource, for transactions within a BigCommerce order.

    Orders API

    Themes API
    API for managing storefront themes.


    Themes API

    Cart API
    Server-to-server API for creating a shopping cart on a BigCommerce store, and for modifying its contents.

    Cart API

    More Is Coming
    We’re continuing to build out our v3 API. Please watch for future announcements.

    View Changelog


    Using the v3 API

    Our v3 API is under active development.

    Over time, we will migrate most of our API v2 endpoints to the v3 API. All new API endpoints will be built exclusively in the v3 API.

    Advantages of our v3 API include:

    1. Fewer API calls to accomplish most tasks

      • Easily include subresources in a resource’s response.
      • Create complex resources and subresources in one API call. (For example, create a product with its variants, images, and custom fields in one API call.)
    2. Ease of pagination

      • meta objects on all resources, with all the details you need to easily paginate.
    3. Metafields

      • Flexible fields to easily store arbitrary data against most objects – these data can be specific to your application, or publicly visible to other applications.
    4. Superior performance and data rates

      • Brand-new code under the hood, with an eye to performance.
      • Including subresources allows you to synchronize lots of data quickly, especially on BigCommerce Enterprise stores.

    The BigCommerce engineering team is building our new merchant-facing features on top of these APIs, so we’ll be thoroughly testing them in our own production environments – also known as dogfooding.

    View our Quickstart Guides at: https://developer.bigcommerce.com/api/guides.

    Have a suggestion, question, or feedback? Please submit it as an issue here: https://github.com/bigcommerce/api/issues.

    Access and Authentication

    All BigCommerce stores have access to the v3 Catalog API.

    The base URI is: https://api.bigcommerce.com/stores/{store_hash}/v3/

    To authenticate, you’ll need to use an OAuth client ID and token, sent along with the following headers:

    The flow to obtain a client ID and token is the same as with the v2 API. You can now obtain OAuth credentials directly from the BigCommerce control panel, as outlined here.

    Existing v2 client IDs and tokens will also work with the v3 API. So, if you’ve already integrated with v2 using our OAuth flow, you should be ready to work with this v3 API!

    What’s New?

    Here are key changes between our v2 and v3 APIs:

    Variants

    Options and Modifiers

    Creating a Product with Its Variants in One API Call

    Including Variants in Product GETs

    Ready-Made Catalog Tree

    Full Access to Modifer Configuration Values

    What’s Not Here?

    If you’re currently consuming our v2 API, you’ll notice that some catalog endpoints and elements are missing from this version. Some of the omissions are intentional; we’re iterating on others, making sure they’re done right.

    Omitted Intentionally

    The following v2 endpoints/elements are intentionally absent from our v3 API:

    Product > Configurable Fields
    Option Sets

    Omitted while Iterating

    The following endpoints/elements are not yet present in our v3 API, while we develop them:

    Product > Complex Rules

    Keep in mind that the majority of rule use cases can already be solved through variant properties and modifier adjusters.

    Product > Open Graph and Accounting Fields

    v2 Catalog API and Control-Panel Interoperability

    The v3 Catalog API is essentially our catalog’s future state. This means that many concepts don’t map visibly to their v2 and control-panel relatives.

    The good news here is we’ve built this API with v2 interoperability in mind. So you should be able to use both APIs simultaneously as you (in an ideal scenario) fully transition all catalog management to v3. The key areas to be aware of are:

    Option Sets

    Product Rules

    Product POST with Variants

    When you include variants in your Product POST, we’ll automatically create all the options and option values for you. If you don’t pass the price and weight with the variants, the product price and weight will be used for the variants on the storefront.

    Here’s a sample POST to https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products:

    {
        "name": "T-shirt",
        "type": "physical",
        "description": "<h4>Wonderful T-shirt</h4>Our favorite branded t-shirt, just for you!",
        "weight": 1,
        "price": 10,
        "categories": [
            23
        ],
        "variants": [{
                "sku": "SKU-BK-CT-SM",
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Black"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Cotton"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Small"
                    }
                ]
            },
            {
                "sku": "SKU-BK-SP-SM",
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Black"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Spandex"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Small"
                    }
                ]
            },
            {
                "sku": "SKU-BK-SP-LG",
                "price": 12,
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Black"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Spandex"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Large"
                    }
                ]
            },
            {
                "sku": "SKU-BL-SP-LG",
                "price": 12,
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Blue"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Spandex"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Large"
                    }
                ]
            },
            {
                "sku": "SKU-BL-SP-SM",
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Blue"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Spandex"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Small"
                    }
                ]
            },
            {
                "sku": "SKU-BL-CT-LG",
                "price": 12,
                "option_values": [{
                        "option_display_name": "Color",
                        "label": "Blue"
                    },
                    {
                        "option_display_name": "Material",
                        "label": "Cotton"
                    },
                    {
                        "option_display_name": "Size",
                        "label": "Large"
                    }
                ]
            }
        ]
    }
    

    When you create a product, we’ll automatically return variants in the response:

    {
        "data": {
            "id": 7137,
            "name": "T-shirt",
            "type": "physical",
            "sku": "",
            "description": "<h4>Wonderful T-shirt</h4>Our favorite branded t-shirt, just for you!",
            "weight": 1,
            "width": 0,
            "depth": 0,
            "height": 0,
            "price": 10,
            "cost_price": 0,
            "retail_price": 0,
            "sale_price": 0,
            "tax_class_id": 0,
            "product_tax_code": "",
            "calculated_price": 10,
            "categories": [23],
            "brand_id": 0,
            "option_set_id": 510,
            "option_set_display": "right",
            "inventory_level": 0,
            "inventory_warning_level": 0,
            "inventory_tracking": "none",
            "reviews_rating_sum": 0,
            "reviews_count": 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": "",
            "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": "2017-10-22T22:01:40+00:00",
            "date_modified": "2017-10-22T22:01:40+00:00",
            "view_count": 0,
            "preorder_release_date": null,
            "preorder_message": "",
            "is_preorder_only": false,
            "is_price_hidden": false,
            "price_hidden_label": "",
            "custom_url": {
                "url": "\/t-shirt-1\/",
                "is_customized": false
            },
            "base_variant_id": null,
            "variants": [{
                "id": 25840,
                "product_id": 7137,
                "sku": "SKU-BK-CT-SM",
                "sku_id": 25041,
                "price": null,
                "calculated_price": 10,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5416,
                    "label": "Black",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5417,
                    "label": "Cotton",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5418,
                    "label": "Small",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }, {
                "id": 25841,
                "product_id": 7137,
                "sku": "SKU-BK-SP-SM",
                "sku_id": 25042,
                "price": null,
                "calculated_price": 10,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5416,
                    "label": "Black",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5419,
                    "label": "Spandex",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5418,
                    "label": "Small",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }, {
                "id": 25842,
                "product_id": 7137,
                "sku": "SKU-BK-SP-LG",
                "sku_id": 25043,
                "price": 12,
                "calculated_price": 12,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5416,
                    "label": "Black",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5419,
                    "label": "Spandex",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5420,
                    "label": "Large",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }, {
                "id": 25843,
                "product_id": 7137,
                "sku": "SKU-BL-SP-LG",
                "sku_id": 25044,
                "price": 12,
                "calculated_price": 12,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5421,
                    "label": "Blue",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5419,
                    "label": "Spandex",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5420,
                    "label": "Large",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }, {
                "id": 25844,
                "product_id": 7137,
                "sku": "SKU-BL-SP-SM",
                "sku_id": 25045,
                "price": null,
                "calculated_price": 10,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5421,
                    "label": "Blue",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5419,
                    "label": "Spandex",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5418,
                    "label": "Small",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }, {
                "id": 25845,
                "product_id": 7137,
                "sku": "SKU-BL-CT-LG",
                "sku_id": 25046,
                "price": 12,
                "calculated_price": 12,
                "weight": null,
                "calculated_weight": 1,
                "width": null,
                "height": null,
                "depth": null,
                "is_free_shipping": false,
                "fixed_cost_shipping_price": null,
                "purchasing_disabled": false,
                "purchasing_disabled_message": "",
                "image_url": "",
                "cost_price": 0,
                "upc": "",
                "mpn": "",
                "gtin": "",
                "inventory_level": 0,
                "inventory_warning_level": 0,
                "bin_picking_number": "",
                "option_values": [{
                    "id": 5421,
                    "label": "Blue",
                    "option_id": 2319,
                    "option_display_name": "Color"
                }, {
                    "id": 5417,
                    "label": "Cotton",
                    "option_id": 2320,
                    "option_display_name": "Material"
                }, {
                    "id": 5420,
                    "label": "Large",
                    "option_id": 2321,
                    "option_display_name": "Size"
                }]
            }],
            "images": [],
            "primary_image": null,
            "videos": [],
            "custom_fields": [],
            "bulk_pricing_rules": []
        },
        "meta": {}
    }
    

    Expanding Product Sub-Resources on GET

    You can include sub-resources on a product, as a comma-separated list, by using include={sub-resources} as a query string. Valid expansions currently include variants, images, custom_fields, and bulk_pricing_rules. For instance, if you wanted variants and custom fields to also return in the product response, you’d:

    GET:
    https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products?include=variants,custom_fields