NAV
  • Welcome to the v3 API
  • 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.

    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

    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

    Using the v3 API

    The 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 v3 APIs 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?

    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.

    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:

    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