B2B GraphQL API

Introduction

The REST Management API you’ll explore throughout this course is the optimal API to power various back-end integrations with B2B Edition, as well as certain privileged interactions in your storefront experience.

For integration points that are focused more heavily on driving storefront user interfaces, B2B Edition also offers a GraphQL Storefront API.

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. The B2B GraphQL API is used to power the built-in Buyer Portal interface.

B2B GraphQL Basics

All B2B GraphQL requests are sent to a common endpoint:

https://api-b2b.bigcommerce.com/graphql

The specific context of a request, including the store it is targeted at, is determined by GraphQL arguments and the authentication token included in the request headers.

The B2B GraphQL API is a Storefront API, meaning that the specific queries and mutations it supports are centered around enabling shopper actions and are usually performed on behalf of a specific storefront user. This means that B2B GraphQL is not the appropriate API 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.

The GraphQL API’s storefront context and authentication mechanism make it a viable choice for requests sent directly from the client side (the user’s browser) or the server side.

You can explore the full docs and schema in the B2B GraphQL Playground.

GraphQL Authentication

Any B2B GraphQL request falls into one of two categories: anonymous requests or requests requiring authentication. Which category a request falls into simply depends on the GraphQL queries/mutations included in the request.

A few queries and mutations can be made anonymously, as they don’t require the context of any specific storefront user. But most queries and mutations deal with specific company data, and these requests require a user-specific bearer token identifying the user on whose behalf the request is being made.

This token is obtained with the login mutation, which requires the customer credentials of the end user.

Example Request:

mutation {
    login(
        loginData: {
            storeHash: "pki...",
            email: "user@example.com",
            password: "MyPassword123..."
        }
    ) {
        result {
            token
        }
    }
}

For subsequent GraphQL requests, the token obtained from this user login operation is then included in a header in the following format to authenticate the user and authorize them for the appropriate data:

Authorization: "Bearer {token}"

Bearer tokens can also be generated with a current customer JSON Web Token (JWT) on Stencil storefronts using the same login mutation. You will need to generate a JWT before you can perform the login mutation, see the Customer Login API article for more information about how to create JWTs.

Example Request:

mutation Login($jwt: String!) {
 loginWithCustomerLoginJwt(jwt: $jwt) {
   customer {
     entityId
     email
   }
   customerAccessToken {
     value
     expiresAt
   }
 }
}

Resources

• B2B GraphQL Playground
• Customer Login API