Introduction to B2B GraphQL
Introduction
Two different GraphQL APIs support B2B operations from your storefront applications. The B2B GraphQL API is purpose-built for B2B Edition and covers the full suite of B2B shopper actions. The standard GraphQL Storefront API also supports B2B operations. Its coverage is currently limited, but it’s expanding over time as more B2B capabilities are added.
The B2B GraphQL API is purpose-built for B2B Edition and provides a dynamic method for querying and modifying B2B Edition data. It powers the built-in B2B Edition Buyer Portal interface and can power your own custom storefront development as well, whether that involves direct customizations to the Buyer Portal, independent features in your Stencil storefront, or an integration with a custom headless implementation.
With a strong type system and a dynamic query structure, GraphQL is optimized for front-end applications, where full control over what data is requested and received is important for performance and responsiveness.
Storefront Context
Both of these are storefront APIs, meaning that the specific queries and mutations they support are centered around enabling shopper actions and are usually performed on behalf of a specific storefront user. This means that a storefront API is not the appropriate tool to, for example, manage the sales staff in your store. Submitting a quote request from a company user, however, is a task for which it is well suited.
In short, a storefront API is personalized to a shopper’s context and designed to facilitate that shopper’s interactions.
BigCommerce GraphQL Storefront API
The GraphQL Storefront API is BigCommerce’s core storefront API, enabling shopper actions like browsing the catalog, managing carts, and completing checkout on your custom storefronts and headless applications. Alongside these core platform capabilities, it supports a limited but expanding set of B2B operations.
For extensive coverage of the GraphQL Storefront API and its conventions, see the dedicated GraphQL Storefront API course.
This API also has its own approach to authentication and customer context, which differ from the B2B GraphQL API. See the dedicated course for full details.
This course will cover those operations that are specific to B2B workflows. Currently, this API supports these B2B-specific operations:
- Company registration
B2B GraphQL API
The B2B GraphQL API is purpose-built for B2B Edition and provides full coverage for all B2B-related operations.
All B2B GraphQL requests are sent to a common endpoint:
The specific context of a request, including the store it is targeting, is determined by GraphQL arguments and the authentication token included in the request headers.
What Can You Do with B2B GraphQL
The major capabilities of the B2B GraphQL API include:
- Company registration
- User authentication
- Managing company users and address book
- Submitting and managing quotes
- Crafting shopping lists
- Fetching orders, invoices, and payments
- Initiating BigCommerce checkout from a quote or an invoice
- Initiating a masquerade session for Super Admin users
B2B GraphQL in Your Front-end
The B2B GraphQL API is already an integral part of the built-in B2B Buyer Portal that drives the B2B shopper experience in BigCommerce storefronts.
When you need to customize the core functionality or presentation of the Buyer Portal, or modify the GraphQL powering the portal’s components, the open source codebase enables you to build out your own implementation for deployment in your storefront. Proficiency in the B2B GraphQL API is key to effectively customizing the Buyer Portal.
However, for less intrusive customization or custom features outside the areas of the storefront handled by the Buyer Portal, it’s also possible to consume the GraphQL API in your own standalone scripts or side apps.
Whether you’re working within the Buyer Portal, directly within a BigCommerce theme, or in your own application, the B2B GraphQL API is the key entry point to interacting with storefront B2B Edition data.
The B2B GraphQL Playground
The B2B GraphQL Playground is a key resource for exploring the full schema and capabilities of the API.
The Playground offers a few key features that will assist you as you integrate the B2B GraphQL queries and mutations into your custom development:
Live GraphQL Console
The main interface is an in-browser console for testing out your queries and mutations, live, with your B2B Edition data.
For requests requiring authentication, as we’ll explore shortly, the Playground interface supports manually pasting a Bearer token into the request headers.
This console is a great alternative to a dedicated API client for quick, one-off tests.
Docs
The Docs tab is a dynamic explorer allowing you to drill into any part of the B2B GraphQL schema. Use this comprehensive reference to see the full details of every query, mutation, and data type, in an intuitive relationship-based interface.
Schema
The Schema tab contains a full reference of the B2B GraphQL types, expressed in GraphQL Schema Definition Language. This schema can also be downloaded.