Using graphql storefront api mutations

Topic summary

Issue: A developer building a headless Shopify store with Gatsby and React is struggling to implement Storefront API mutations, specifically for customer creation. While they can query product/collection data using gatsby-source-shopify, they’re unsure how to execute mutations in their React app.

Initial Setup: The developer configured gatsby-source-graphql to access the Admin API and successfully tested a customerCreate mutation in GraphiQL and Insomnia.

Key Question: How to execute mutations in the Gatsby-React app—does this require Apollo Client?

Response Guidance:

  • Apollo Client isn’t mandatory; alternatives include fetch, graphql-request, or axios
  • Recommended approach: Set up a GraphQL client, construct the mutation query, send requests to the Shopify endpoint with proper authentication headers (X-Shopify-Storefront-Access-Token), and handle responses
  • Resources provided: Gatsby-Shopify tutorial, starter project, and Shopify GraphQL API documentation

Follow-up Issue: Another user asks whether X-Shopify-Storefront-Access-Token equals PRIVATE_STOREFRONT_API_TOKEN, reporting an UNAUTHORIZED error in their local environment.

Status: Ongoing—authentication token confusion remains unresolved.

Summarized with AI on November 9. AI used: claude-sonnet-4-5-20250929.

I am testing and building a headless shopify using gatsby-shopify-starter template. (developing in React)

As far as I know I can easily query all the product and collection information with the help of ‘gatsby-source-shopify’.

However I am having trouble using Storefront API, specially creating a customer using mutation.

I used gatsby-source-graphql plugin to build the admin graphql schema :

{
            resolve: `gatsby-source-graphql`,
            options: {
                typeName: 'ShopifyAdmin',
                fieldName: 'admin',
                url: `https://storedomain.myshopify.com/admin/api/2021-07/graphql.json`,
                headers: {
                    'X-Shopify-Access-Token': process.env.SHOPIFY_SHOP_PASSWORD,
                },
                fetchOptions: {
                    method: 'POST',
                },
            },
        }

My question is: How would you be able to use mutation to the https://fingersuit-japan.myshopify.com/admin/api/2021-07/graphql.json Do I need to install and use apollo client in order to use mutation?

Already tested with GraphiQL app and with Insomnia the following GraphQL query:

mutation customerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    customerUserErrors {
      code
      field
      message
    }
    customer {
      id
    }
  }
}

Now how am I able to do this in my headless shopify-gatsby app using React? Are there any guides for it?

1 Like

Hello @young1c

To use GraphQL mutations in your headless Shopify-Gatsby app using React, you don’t necessarily need to install and use Apollo Client. While Apollo Client is a popular choice for GraphQL in React applications, you have other options as well, such as using the built-in fetch function or other GraphQL clients.

Here’s a general approach to performing GraphQL mutations in a headless Shopify-Gatsby app:

  1. Set up the GraphQL client: Choose a GraphQL client library or use the built-in fetch function to make HTTP requests. You can install libraries like graphql-request, axios, or use fetch directly.

  2. Construct the GraphQL mutation: Define the mutation query in a separate file or directly in your React component. Use the gql tag from the graphql-tag library or similar tools to parse the GraphQL query.

  3. Send the mutation request: Use the chosen GraphQL client to send the mutation request to the Shopify GraphQL API endpoint ([https://fingersuit-japan.myshopify.com/admin/api/2021-07/graphql.json](https://fingersuit-japan.myshopify.com/admin/api/2021-07/graphql.json)). Include the required headers, such as the X-Shopify-Storefront-Access-Token, to authenticate and authorize the request.

  4. Process the response: Handle the response from the GraphQL mutation. You can check for errors in the response and extract the relevant data as needed.

As for guides and resources, Shopify provides comprehensive documentation on using GraphQL with their API. You can refer to the Shopify GraphQL API documentation, which covers various aspects of working with GraphQL in a Shopify context. Additionally, there are community-driven resources and tutorials available that specifically focus on using React and Gatsby with Shopify, which can provide step-by-step guidance on integrating and using mutations in your app.

Here are a few resources to get you started:

These resources should provide you with the necessary information and examples to integrate GraphQL mutations in your headless Shopify-Gatsby app using React.

Thanks

Is X-Shopify-Storefront-Access-Token the same PRIVATE_STOREFRONT_API_TOKEN?

I’m getting code UNAUTHORIZED error when I try to fetch in my local environment.