Querying From External Systems

Plan: Developer Foundations

Lesson 8 of 28 · 15 min

If you wish to use the GraphQL Storefront API from an external system, such as a headless storefront, there are a few considerations:

• In which Channel do you wish to run requests?
• Are you running requests from a server or a front-end application/browser?
• Does a request require the context of a customer, or does it deal only with anonymous information?

I want to run requests in the context of the store’s default channel (Channel ID 1)

There are three options for public URLs that you can use to run requests:

• The store’s default storefront URL, e.g. https://store.com/graphql
• The store’s canonical URL, e.g. https://store-STOREHASH.mybigcommerce.com/graphql
• The store’s custom checkout domain

I want to run requests from the perspective of another Channel

In this case, you should use the Channel’s Permanent URL of the form https://store-STOREHASH-CHANNELID.mybigcommerce.com/graphql. In order for the Channel’s Permanent URL to be available, you must create a Site for the channel.

For example, if your store hash is abc123 and your channel ID is 456, the correct URL would be https://store-abc123-456.mybigcommerce.com/graphql. Note that you must create your Storefront API Token with the same channel ID, or your request will be rejected.

I want to run requests from a browser (e.g. React app)

In this case, use a standard Storefront API Token with the proper allowed origins set. Session cookies will provide customer context when it exists.

I want to run requests from a server and I don’t need a customer context

In this case, use a Private Token without sending a X-Bc-Customer-Access-Token header.

I want to run requests from a server and the customer context matters

In this case, use a Private Token and provide a customer access token in the X-Bc-Customer-Access-Token header.

When server-side requests are made from an application like a headless storefront, the required GraphQL Storefront interactions are often extensive and varied. A request for store settings, for example, may require no customer context. The majority of other requests likely do need a customer context if it exists; queries for catalog data may be affected by customer pricing or visibility, and cart and checkout operations are customer-specific. It’s common to simply provide a customer access token (if it exists) for all requests. If you instead choose to selectively include a customer access token for some requests and not others, make sure you carefully consider which requests are affected (or might be in the future) by customer context.

Resources

• Querying from External Systems
• CORS
• Sites and Routes
• List of GraphQL Error Messages