Skip to main content

Fetching API data on the storefront

You can build and customize GraphQL queries to display ecommerce data on your storefront, such as products and shopping cart information. In this guide, you will find the basic concepts and steps to implement this in your FastStore project.

Before you start

Before getting to work on your code, there are some concepts you should be familiar with when it comes to the FastStore API.

The FastStore API extends the data layer of your preferred static site generation framework (e.g., Next.js, Gatsby), including data from an ecommerce platform. Because of that, ecommerce information is queried for a given page only when that page is built.

This means that updating a given product's information on your ecommerce platform does not automatically update the information displayed on a previously built product page. Whenever you wish to update the information displayed on your website according to your ecommerce platform data, you should redeploy your website, which will trigger page re-generation.

We also recommend that you take the time to learn more about data fetching in the context of the framework you are using, by checking the corresponding article:

Fetching ecommerce data

There are three main steps to building your page code to fetch data from the FastStore API:

  1. Building a query.
  2. Importing the generated query.
  3. Using the data.

Below you can see more details about each step along with code examples.

1. Building a query

First, you need to know what API data you want to use on your page and how to structure a GraphQL query to get it. It is a good idea to check the FastStore API reference on queries. You can also use a GraphQL IDE to build and test queries to make sure it works as expected.

Once you have your query structure, you can pass that as a variable on your code by using the gql tag, like in the example below.

import { gql } from '@faststore/graphql-utils'
...
const query = gql`
query ProductPageQuery($slug: String!) {
product(locator: [{ key: "slug", value: $slug }]) {

seo {
title
description
canonical
}

brand {
name
}

sku
name
description
}
}
`

Queries must be declared in this way on each page on which you wish to use their data. To reuse query snippets across multiple files, you may use GraphQL fragments. In the example below you can see an SEO fragment being used to build the same query as the example above.

Declaring the fragment:

import { gql } from '@faststore/graphql-utils'
...
export const fragment = gql`
fragment ProductSeoFragment_product on StoreProduct {
seo {
title
description
canonical
}
}
`

Using the fragment, on the same file or a different one:

import { gql } from '@faststore/graphql-utils'
...
const query = gql`
query ProductPageQuery($slug: String!) {
product(locator: [{ key: "slug", value: $slug }]) {

...ProductSeoFragment_product

brand {
name
}

sku
name
description
}
}
`

Building queries on Gatsby

If you are building queries on a store that uses Gatsby, keep in mind that you must also use the graphql tag in some contexts. Using graphql causes the query to be processed by Gatsby, while gql does not. Because of that, as a general rule, use graphql for queries that should be run during the page build and gql for the rest.

Also, some queries may not run properly during the build. If you run into that issue, try using gql.

See in the following example how the queries in the Next.js base store product page and the corresponding page of the Gatsby base store compare to each other.

import { gql } from '@faststore/graphql-utils'
...
const query = gql`
query ServerProductPageQuery($slug: String!) {
product(locator: [{ key: "slug", value: $slug }]) {
id: productID

seo {
title
description
canonical
}

brand {
name
}

sku
gtin
name
description

breadcrumbList {
itemListElement {
item
name
position
}
}

image {
url
alternateName
}

offers {
lowPrice
highPrice
priceCurrency
offers {
availability
price
priceValidUntil
priceCurrency
itemCondition
seller {
identifier
}
}
}

isVariantOf {
productGroupID
}

...ProductDetailsFragment_product
}
}
`

2. Importing the generated query

Once you have declared your query on the page code, you can trigger the generation of your query types by running this command:

yarn generate
caution

Whenever you make changes to your declared queries you must regenerate the types with the command above. Otherwise, you will not be able to use the data.

Then you must import the types generated, like in this example:

import { gql } from '@faststore/graphql-utils'
import type { ProductPageQueryQuery } from '@generated/graphql'
...
const query = gql`
query ProductPageQuery($slug: String!) {
product(locator: [{ key: "slug", value: $slug }]) {
## Query fields
}
}
`
info

Note that, like in this example, the auto-generated query types names are formed by adding the word "Query" to the end of the query name you declared.

3. Using the data

Having built a query and imported the generated type, you can effectively destructure and use the API data in your page function, like in the example:

...
type Props = ProductPageQueryQuery

function Page({ product }: Props) {
const { seo } = product
const title = seo.title
const description = seo.description
...
}
...

Complete code example

After completing the steps described above, your code should look like the example below.

info

It is also a good idea to see how data fetching is implemented in pages from FastStore starters, such as:

import { gql } from '@faststore/graphql-utils'
import type { ProductPageQueryQuery } from '@generated/graphql'
...

type Props = ProductPageQueryQuery

function Page({ product }: Props) {
const { seo } = product
const title = seo.title
const description = seo.description
...
}
...

const query = gql`
query ProductPageQuery($slug: String!) {
product(locator: [{ key: "slug", value: $slug }]) {

seo {
title
description
canonical
}

brand {
name
}

sku
name
description
}
}
`

Didn't find your answers? Ask the Community. For documentation suggestions, submit your feedback.

JOIN THE COMMUNITY