⚠️ After March 18, 2024, the FastStore documentation will be migrated to the Developer Portal. For more information, access the official release note.

API extension

In this track, learn how to extend the FastStore API schema by adding new data to the existing queries (opens in a new tab).

While the FastStore API provides a GraphQL schema for ecommerce (opens in a new tab) that covers a general use case, some stores may need to access other, more specific, information.

Note that adding additional API endpoints to your storefront can potentially impact site performance, as already covered in the guide Best practices for fetching data. If you need to retrieve more data, you can achieve this by extending the FastStore API schema and incorporating new data into the existing queries (opens in a new tab).

Main concepts

  • GraphQL Optimizations & types

    GraphQL Optimizations are essential for optimizing your GraphQL server and TypeScript types. They provide benefits such as:

    • Build-time generated mappings of declared queries
    • Improved efficiency and security
    • Enforcement of predefined operations

    Without these optimizations, any modifications to the GraphQL schema, such as adding or removing fields from a query or altering a GraphQL type, won't be reflected in the store.

    Additionally, GraphQL query optimizations update TypeScript types for the API to match schema changes seamlessly.


  • GraphQL Optimization automation

    GraphQL optimizations are seamlessly executed, requiring no direct intervention from end developers. They are automatically triggered every time you start a development server (yarn dev) or builds the store (yarn build). Resolver changes are automatically and instantly visible, without the need for manual optimization generation.


  • Extendable queries

    Extendable queries in FastStore's GraphQL API are predefined GraphQL queries that serve as a foundation for retrieving data from the API. These queries allow you to add or modify fields within the query to tailor the data retrieval process to the store specific needs.


Best practices for fetching data

Site performance tends to get worse as more API requests are made by a page. Because of this, the best practices for fetching data on your storefront involve getting precisely the data you need with the minimum number possible of requests to the FastStore API. The sections below go over what you can do to minimize the API requests of your pages.

Fetch only the data you need

GraphQL allows you to customize your query to get precisely the data you need, which reduces the data returned from the requests. Double-check your queries to make sure they are not over-fetching.

This also means that you must be mindful of the data brought into your query by GraphQL fragments (opens in a new tab). Use them only when they do not include unnecessary data.

Do not send requests to other APIs

When building your storefront with FastStore, to avoid comprimising the website performance and lead to 504 timeout errors, do not send requests to APIs other than the FastStore API. If you need to access other data not available in the native FastStore API schema, you must do this by using API extension.

If you need data that is not available on the native FastStore GraphQL schema (opens in a new tab), check the root object (opens in a new tab). The GraphQL root object (opens in a new tab) represents the top-level object returned to a query. You can see what data is available in the root object by typing the root param in your store code, as you can see in the step 2 of Creating resolvers.

Avoid custom API Routes

We do not recomend using Next.js API Routes (opens in a new tab) other than the ones already built in FastStore.

If you do use this type of function, you must be mindful to always check which ones are actually running and remove the ones that are not.

ObjectsExtending API schemas