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

    Storefront Widgets (Early Access)
    API-first approach to associating content (HTML, CSS, JavaScript, rich media) with a storefront’s regions.

    Storefront Widgets API


    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:

    • Accept: application/json
    • X-Auth-Client: {client_id}
    • X-Auth-Token: {oauth_token}

    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?

    • Variants
      • Every purchasable entity in the catalog is now a variant. When you create a product without any options, we automatically create a variant for you. This enables enhanced flows around inventory management, such as the ability to solely use the variants endpoint to manage inventory levels.
    • Options and Modifiers
      • There is now a clear separation of options that define variants versus those that are modifiers of a variant. This enables us to simplify the creation and management of variant prices and modifier adjusters. It removes the need to use complex rules, in all but the most extreme cases.
      • Options and modifiers can also be attached directly to the product, without the requirement to create an option set beforehand.
    • Creating a Product with its Variants in One API Call
      • When creating an initial catalog, you can send the core product and variant data in the same request. This helps you create more performant, managable codebases. We’ll handle the option and option value creation for you.
    • Including Variants in Product GETs
      • Following our goal of streamlining catalog management, you can now request to ?include=variants (along with other resources). This further eliminates API calls.
    • Ready-made Catalog Tree
      • There’s now an endpoint specifically for building out the catalog tree, which previously took considerable work to construct.
    • Full Access to Modifer Configuration values
      • Properties like number-only field limits, and product-list inventory adjustment settings, are now available via this API. This exposes more than 20 properties previously unavailable to our developers.

    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.

    • Intentional
      • Product -> Configurable Fields
        • Modifiers should now be used for any use case where you’d use configurable fields. You can attach modifiers to products as well and they cover a larger array of uses.
      • Option Sets
        • In v3, you attach options directly to products. So option sets are not required, and v3 includes no endpoint to manage options sets. However, v3 will respect option sets that have been attached via v2 or the control panel.
    • Iterating
      • Product -> Complex Rules
        • Keep in mind that the majority of rule use cases can already be solved through variant properties and modifier adjusters.
      • Product -> Reviews
      • Product -> Videos
      • Product -> Downloads
      • Product -> Google Search Mappings
        • Might instead bring fields onto variant entity as properties/metadata.
      • Product -> Open Graph and Accounting Fields
        • Might group into their own product objects, to keep resource clean.

    You can see how we’re planning to iterate by looking at the public API roadmap.

    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
      • The Product resource in v3 has an option_set_id field that, if set, will prevent you from directly editing product options and modifiers. If you want to edit the option set, you will need to either use v2, or else set the option_set_id field to null. The latter will remove the option set and allow you to directly attach options and modifiers.
      • In our control panel’s Add/Edit Product section, any products created by v3 will have not have an option set applied, but merchants can still edit the options. If the merchant edits/chooses an option set, any variants will be removed from the product.
    • Product Rules
      • Any variant created in v3 with non-null core properties (price, weight, image, purchasablilty) 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.

    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