> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# The API Client

Plan: Developer Foundations

Lesson 12 of 16 · 30 min

## Introduction

Interacting with BigCommerce via the GraphQL Storefront API is a critical part of the Catalyst architecture, enabling dynamic data fetching and manipulation. To simplify this process, the **@bigcommerce/catalyst-client** package provides a convenient way to interact with the GraphQL API, wrapping the native *fetch* API for easier use. In this lesson, we will explore how to leverage this client to efficiently query and manage data within your Catalyst storefront.

## Initializing the Client

The Catalyst API client must be initialized with the appropriate store-specific configuration details (such as the store hash and storefront token). With this config info, the client can then automatically take care of handling the HTTP request details for all GraphQL calls, including authentication.

You can see in *client/index.ts* that this initialization is done automatically by the main Catalyst project codebase.

## The Standard Client Pattern

Let's look at a simple API client example from the built-in queries, from *app/\[locale]/(default)/cart/page-data.ts*:

```js showLineNumbers={false}
...

const CartPageQuery = graphql(
  `
    query CartPageQuery($cartId: String) {
      site {
        cart(entityId: $cartId) {
          entityId
          version
          currencyCode
          ...
        }
        checkout(entityId: $cartId) {
          ...
        }
      }
    }
  `,
  [
    PhysicalItemFragment,
    DigitalItemFragment,
    MoneyFieldsFragment,
    ...
  ],
);

export const getCart = async (variables: Variables) => {
  ...

  const { data } = await client.fetch({
    document: CartPageQuery,
    variables,
    ...
  });

  return data;
};
```

This common pattern performs several tasks:

* Defines a GraphQL string with the query syntax itself.
* Passes this GraphQL string to the function *graphql* (notice that GraphQL fragments are similarly passed to the same function, the results being passed as a second "dependencies" argument for any queries that use them.)
* Passes the GraphQL document returned from *graphql*, along with any relevant variables and options, to the client.
* Extracts data from the expected structure of the GraphQL response.

> **Info**
>
> When architecting your own queries and mutations, it's best to stick to this same pattern.

## Customer Context

The GraphQL Storefront API supports providing the context of a registered BigCommerce customer in any given request, which can affect the data returned. This comes into play if the user has logged in with valid BigCommerce customer credentials. For example, if a customer belongs to a customer group with access to only certain categories or with custom pricing, this will be reflected in the product information returned by GraphQL. Server-side requests like those in Catalyst establish this context by including the customer access token originally obtained during login in a specialized header.

The Catalyst API client supports passing in a *customerAccessToken* config parameter and will take care of including the context in the HTTP request if it's provided. The storefront's authentication implementation also exposes a simple function for retrieving the access token from a logged-in user's session: the function *getSessionCustomerAccessToken* in *auth/index.ts*.

From the cart example:

```jsx showLineNumbers={false}
import { getSessionCustomerAccessToken } from '~/auth';

...

export const getCart = async (variables: Variables) => {
  const customerAccessToken = await getSessionCustomerAccessToken();

  const { data } = await client.fetch({
    document: CartPageQuery,
    variables,
    customerAccessToken,
    ...
  });

  ...
};
```

You can easily use these tools to provide the current customer's context to your own queries. Since this is an optional parameter of the API client, you can be selective about which queries and mutations pass in a customer context and which ones don't. If you're confident that a certain query will not be affected by customer context, making the request anonymous is typically the best option for performance.

## Resources

* [GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api)