Catalyst Client
Catalyst allows you to retrieve info from BigCommerce's APIs through the Catalyst Client.
The client simplifies what you need to do to handle requests and responses. For example, you don't need to construct request URLs, configure request headers, or parse JSON responses. The client uses the channel ID and authorization tokens configured in the .env
file by default.
Methods
-
fetch()
: allows you to interact with BigCommerce's GraphQL Storefront API (opens in a new tab). You can execute all queries and mutations available in BigCommerce's Storefront graph (opens in a new tab). -
fetchSitemapIndex(channelId?: string)
: fetches the sitemap index for the store, which provides a URL to the XML sitemap.
Deprecated
The following method is deprecated and requires the BIGCOMMERCE_ACCESS_TOKEN
to be set in the .env
file.
fetchShippingZones()
: retrieves shipping zones for the BigCommerce store. It sends an HTTP GET request to the BigCommerce Management API (opens in a new tab), but simplifies how you would make a direct request to fetch shipping zones.
Fetch
The following sections describe the fetch()
method.
Parameters
Parameter name | Type | Required? | Description |
---|---|---|---|
document | object DocumentDecoration<TResult, TVariables> | Yes | The GraphQL query or mutation you want to execute. It must be in the form of a string or a GraphQL AST (Abstract Syntax Tree) that defines the query. The DocumentDecoration interface supports types from @graphql-typed-document-node/core and TypedQueryDocumentNode . These ensure the types of variables and results match. The document could be a GraphQL query or mutation. |
variables | object TVariables | No | Variables to be passed to the GraphQL query or mutation. |
customerId | string | No | The ID of the customer to impersonate. If you want to fetch data as a specific customer, you can provide their ID here. This will add an X-Bc-Customer-Id header to the request. |
fetchOptions | object FetcherRequestInit | No | Custom options for the fetch request. FetcherRequestInit extends the global RequestInit interface in JavaScript, which includes parameters such as method , headers , body , and options for caching and credentials. |
channelId | string | No | Allows you to specify a different storefront channel for the request. Defaults to the channel ID in the .env file. |
Request headers
The fetch
method automatically sets the following headers:
"Content-Type": "application/json"
"Authorization": "Bearer <customerImpersonationToken>"
"User-Agent": <backendUserAgent>
- (Optional)
"X-Bc-Customer-Id"
if you provide acustomerId
Return value
The fetch
method returns a promise that resolves to a response object containing the requested data. The response follows the structure defined in the GraphQL query.
-
Return Type:
Promise<BigCommerceResponse<TResult>>
The
BigCommerceResponse
type wraps the actual data returned from the API, whereTResult
represents the expected shape of the response data.Inside
BigCommerceResponse
, thedata
field holds the actual data returned by the GraphQL API, which matches the structure of the query or mutation you executed. -
Error Handling
:If the response is not
ok
(i.e., the request fails), the method throws aBigCommerceAPIError
, which includes the HTTP status and any GraphQL errors returned in the response.
Examples
Get product reviews
The example output in the console:
Error handling
The BigCommerceAPIError
class provides error handling and is instantiated when the fetch fails.
Logging
You can log the request's operation name, type, and execution time to the console, along with the query complexity (opens in a new tab).
To use this feature, enable logging through the CLIENT_LOGGER
environment variable. When you run the fetch
method, it will invoke the requestLogger()
function internally to capture and log the information.