Querying in the Buyer Portal

Introduction

We’ve previously emphasized the relationship between the Buyer Portal and the B2B GraphQL API.

Let’s take a closer look at the Buyer Portal’s core architecture for GraphQL querying and the patterns you can use in your own custom Buyer Portal implementation.

Key Layers

The most significant layers involved with GraphQL querying include:

• Request layer (B3Request): This global object handles the low-level details of HTTP requests, including handling global error behavior. This single entry point handles client-side requests to both the main BigCommerce GraphQL Storefront API and the B2B GraphQL API. We’re mainly concerned with the latter, which are performed with B3Request.graphqlB2B.
• Service layer (@/shared/service/b2b): Domain-focused modules (invoices, orders, quotes, shopping lists, etc.) that define GraphQL operations and call B3Request.graphqlB2B. They hide query strings and response shapes from the rest of the app.

Pages and components don’t deal directly with the GraphQL endpoint URL, headers, or token handling, relying instead on one or both of the above layers.

Making B2B GraphQL Requests

There are two main patterns for making requests to the B2B GraphQL API.

1. Use the B2B request layer directly

For one-off or simple calls, you can use B3Request.graphqlB2B with a query and optional variables. The request layer will:

• Use the correct B2B GraphQL URL for the current environment.
• Add the Authorization: Bearer <B2BToken> header from the store.
• Return the data part of the response, or handle errors (e.g. 40101 → redirect to login, others → snackbar or throw).

Example (query with variables):

import B3Request from "../../../../../../shared/service/request/b3Fetch";
const response = await B3Request.graphqlB2B({
  query: `
    query GetRecentInvoices($limit: Int, $sort: String) {
      invoices(first: $limit, orderBy: $sort) {
        edges {
          node {
            id
            invoiceNumber
            status
          }
        }
      }
    }
  `,
  variables: { limit: 5, sort: "-updatedAt" },
});
// response is the GraphQL "data" object (e.g. { invoices: { edges: [...] } })

You don’t set the URL or the auth header; the request layer does that for you.

2. Use domain-specific B2B service functions

For commonly used queries and mutations, call named functions from @/shared/service/b2b (or its submodules). Each function encapsulates one GraphQL operation and uses B3Request.graphqlB2B internally.

Example — Invoices:

import { getInvoiceList, getInvoiceDetail } from "../../../../../../shared/service/b2b";
// List with filters/pagination
const listData = await getInvoiceList({
  q: "",
  first: 10,
  offset: 0,
  orderBy: "-createdAt",
  status: 1,
  // ...other filter fields
});
// Single invoice
const detail = await getInvoiceDetail(invoiceId);

Service modules live in shared/service/b2b/graphql/ (e.g. invoice.ts, orders.ts, quote.ts). Each file defines:

• GraphQL query/mutation strings (often as template functions that take parameters).
• Exported functions that call B3Request.graphqlB2B({ query, variables }) and return the result.

Using these service functions is the easiest way to incorporate GraphQL data into your own components when your use case matches one of the predefined operations.

The BigCommerce GraphQL Storefront API

Recall that the Buyer Portal actually uses both the B2B GraphQL API and the standard BigCommerce GraphQL Storefront API.

If you need to make requests to the GraphQL Storefront API from your Buyer Portal code, the B3Request object handles these as well:

• graphqlBC makes requests directly to the /graphql endpoint on your storefront domain.
• graphqlBCProxy proxies requests through an endpoint on the B2B backend.

We’ll discuss the reason for these two methods in a future section, as we explore the authentication flow behind the portal’s API requests. For now, just be aware that graphqlBC is appropriate for Stencil storefronts and graphqlBCProxy is appropriate for headless storefronts. Examine the codebase for examples of how window.B3.setting.platform is inspected to make this distinction.