B2B Edition GraphQL Storefront API overview

The B2B Edition GraphQL Storefront API provides a dynamic method for querying and modifying B2B Edition data from your storefront applications. The GraphQL Storefront API powers the Buyer Portal and allows you to customize your buyers’ B2B experience on hosted and headless storefronts.

Using the B2B Edition GraphQL Storefront API, you can:

Register new Company accounts.
Authenticate users as they access the Buyer Portal.
Manage Company information like user roles and saved addresses.
View, submit, and generate carts from sales quotes.
Create and approve Shopping Lists.
Retrieve detailed information for orders, invoices, and payments.
Initiative a Masquerade session as a Super Admin user.

While these APIs are similar to the BigCommerce GraphQL Storefront API, they use a different request path (https://api-b2b.bigcommerce.com/graphql). They also have distinct schemas and usage considerations.

It is best practice to use the GraphQL Storefront API if you are developing on the Buyer Portal experience. While the legacy Stencil storefront experience uses the REST Storefront API by default, you can also use GraphQL as well.

Accessing the GraphQL Playground

The B2B Edition GraphQL Playground provides a space for you to formulate and test queries and mutations. It includes resources like query schemas and documentation on fields and arguments to help you construct requests.

Input your request on the left side of the playground along with any variables and headers. Click Play to send the request and view the results on the right side. You can also hover your cursor over parts of your request to get more information on a field or view error details.

B2B GraphQL Playground

Most GraphQL requests in B2B Edition reference Company account information and require authentication for a successful response. However, we have provided an anonymous example query below that does not require authentication to familiarize yourself with the GraphQL Playground.

Example query: Get Store Currencies


query currencies ($storeHash:String!, $channelId:String!){
  currencies (storeHash: $storeHash, channelId:$channelId) {
    currencies {
      id
      name
      currency_code	
    }
  }
}

Authentication

B2B Edition GraphQL Storefront API queries and mutations are either anonymous or authenticated. Anonymous queries and mutations do not require an authentication header or token. Users can make anonymous requests, such as the login and companyCreate mutations, without being logged in to a storefront user account.

Authenticated queries and mutations use storefront authTokens to authenticate requests. You must add your token to the request header in the following format: "Authorization": "Bearer [token value]".

Storefront authTokens are always associated with a specific Company user or B2C customer, and they don’t rely on storefront cookies. You can use them in both client- and server-side contexts.

To learn more about generating and using storefront authTokens, see Authentication for hosted storefronts.

Querying within the Buyer Portal

The B2B Edition GraphQL Storefront API allows you to make calls directly from within the Buyer Portal, a Stencil theme, or a script in the store’s Script Manager . If you are developing in the Buyer Portal experience, it is best to make most customizations within the Buyer Portal itself, and to use scripts or side apps for smaller changes or customizations to non-Buyer Portal areas of the storefront.

Below, we’ve provided examples of how you can use JavaScript’s Fetch API to create scripts for anonymous and authenticated GraphQL queries. The first example uses the Handlebars objects to return the store hash and channel ID of the storefront. The second example uses window.b2b.utils.user.getB2BToken() to retrieve the storefront authToken of a logged-in Company user.

Anonymous query using Handlebars objects


<script>
  fetch('https://api-b2b.bigcommerce.com/graphql', {
    method: 'POST',
    credentials: 'same-origin',
    headers: {
      'Content-Type': 'application/json' // anonymous request; no storefront authToken needed
    },
    body: JSON.stringify({
      query: `query MyFirstQuery ($storeHash:String!, $channelId:String!) {
          currencies (storeHash: $storeHash, channelId: $channelId) {
            currencies {
              id
              name
              currency_code	
            }
          }
	}`,
      variables: {
          storeHash: "{{ settings.store_hash }}",
          channelId: "{{ settings.channel_id }}"
      }
    })
  })
  .then(res => res.json())
  .then(data => console.log(data)) // will log JSON result to browser console
  .catch(error => console.error(error));
</script

You can use clients to simplify your GraphQL implementations by aligning code generation with B2B Edition’s schemas. See our Best Practices documentation to learn more.

Pagination

All queries that return a list of items follow the Cursor Connections pattern. This specification allows you to paginate results and communicate whether additional results are available. To learn more about utilizing pagination, see the BigCommerce GraphQL Storefront API overview.

Extra Fields

Extra fields are custom information fields that you can configure in the B2B Edition control panel for the following B2B Edition records:

Company accounts
Company users
Company addresses
B2B orders
Invoices
Sales quotes

You can return extra field information in queries as well as specify field values in mutations that create or update new records. See the query below for how you can include extra fields in your requests.


query GetInvoices {
    invoices {
        edges {
            node {
                extraFields {
                    fieldName
                    fieldValue
                }
            }
        }
    }
}

Keep in mind the following considerations when including extra fields in requests:

The fieldValue is always a string, regardless of the extra field’s configured data type.
You can configure extra fields that are not visible to the end user on the storefront.
Mutations will fail if they include:
- Extra fields marked as required with empty values.
- Extra fields marked as unique with values that exist on another record.

Complexity Limits

Complexity is a measure of the projected load for a given GraphQL query. A query’s complexity score takes into account the number and depth of objects in the query.

The B2B Edition GraphQL API sets a complexity limit of 4,500 per request. For instructions and examples of reducing the complexity of your queries, see the BigCommerce GraphQL Storefront API overview.

FAQ

How can I make requests in the context of a specific storefront channel?

To make a storefront-specific request, you must include the storeHash and channelId variables in the argument. Note that some records, such as Company accounts and Super Admins, are not exclusive to a single channel in your store. Go to the GraphQL Playground to see which queries and mutations require these fields and how to format them in the request.

How can I create a custom Buyer Portal or modify the functionality of my existing Buyer Portal?

Use the open source repository to customize a self-hosted version of the Buyer Portal on a storefront. See the README file in the repository to learn more.

Where can I find more information about an error message in a response?

See GraphQL HTTP status codes for a list of error messages and explanations.

Can I create webhooks to notify me when certain B2B Edition events occur?

Yes, you can create webhooks to receive basic information on requests made with B2B Edition’s GraphQL Storefront APIs. See B2B Edition Webhooks for a full list of supported events.

Resources

Did you find what you were looking for?