Menu
Guides
API Reference
App Development
Storefront Development
VTEX IO Apps
Troubleshooting
Release Notes
Storefront Development
Getting started with storefront solutions
FastStore
Store Framework
CMS Portal (Legacy)
Storefront best practices

Extending API schemas

9 min read
This guide will teach you how to extend VTEX and third-party APIs to suit your store's needs. By extending these APIs, you'll gain the ability to efficiently access and modify essential data, ensuring seamless customization to meet your specific needs.

Before you begin

Ensure consistency with API extension best practices

When extending the FastStore API schema, avoid overfetching data on your storefront. Refer to the Best practices for fetching data on your storefront for more information.

Ensure your development server is active

Ensure that your development server is up and running while developing to observe changes promptly. Use the command yarn dev in the terminal to run the development server and monitor changes effectively.

Extending VTEX API Schemas

FastStore streamlines the data utilization from VTEX APIs not directly exposed by the FastStore API.
Since FastStore uses GraphQL, you need to include type definitions and resolvers to fetch the desired data. To define new type definitions and resolvers for FastStore using GraphQL, follow the instructions below.

Instructions

Step 1 - Preparing the folders and files

To declare a new type definition and resolver, create the following directory structure:
  1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:

    _10
    mkdir graphql

  2. Inside the new graphql folder, create the vtex subfolder.

    _10
    mkdir vtex

  3. In the vtex folder, create resolvers and typeDefs subfolders.

    _10
    mkdir resolvers typeDefs

    The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs paths are mandatory, but you can organize the files inside those directories as you wish.
  4. Create an index.ts file inside the resolvers folder.
Once you have created the necessary folders, you will have a folder structure for the VTEX API Schema Extensions in the src/graphql/vtex folder similar to the following:

_11
starter.store/
_11
└─ src/
_11
└─ graphql/
_11
└─ vtex/
_11
├─ resolvers/
_11
└─ index.ts
_11
└─ <resolverName>.ts
_11
└─ …
_11
├─ typeDefs/
_11
└─<typeName>.graphql
_11
└─ …

In the code example above, the type definitions and resolvers files were created in <resolverName>.ts and <typeName>.graphql.

Step 2 - Creating type definitions (typeDefs)

Your new type definitions set the data structure for your new fields, extended from the existing FastStore API GraphQL queries and types.
  1. Create a new <typeName>.graphql file inside the vtex/typeDefs folder. For example, if we extend the StoreProduct type from the FastStore API, the name of the file should be product.graphql.
    The organization inside the vtex/typeDefs folder is flexible. You can create multiple typeDefs files or group them all together in one file. During the build process and when running the local server file, all .graphql files under this directory will be considered.
  2. To extend StoreProduct, let's add a customData required field in product.graphql, which should return a string value. This field can store custom information related to a product in your store. For example, you might use this field to store additional product details that are not in the native FastStore API schema.
    graphql/vtex/typeDefs/product.graphql

    _10
    extend type StoreProduct {
    _10
    """
    _10
    Custom data extending StoreProduct
    _10
    """
    _10
    customData: String!
    _10
    }

    The typeDefs files must have a .graphql extension. Also, index.ts is necessary for resolvers but not required for typeDefs.
Refer to the next step to create the resolvers to provide the actual data to the customData field.

Step 3 - Creating resolvers

Now, you'll create a resolver to define how the new customData field should be resolved, specifically what data or logic should be associated with it when queried.
  1. Create a new <resolver>.ts file inside the vtex/resolvers folder. Let's continue using the StoreProduct type example. That means the name of the file will be product.ts.
    The organization inside this folder is flexible. You can create multiple resolver files or group them all together in one file.
  2. Define the resolver in the product.ts file. This resolver specifies how to fetch the data for the customData field based on the root object, which represents the StoreProduct.
    graphql/vtex/resolvers/product.ts

    _11
    import type { StoreProductRoot } from "@faststore/api";
    _11
    _11
    const productResolver = {
    _11
    StoreProduct: {
    _11
    customData: (root: StoreProductRoot) => {
    _11
    return "My item id: " + root.itemId;
    _11
    },
    _11
    },
    _11
    };
    _11
    _11
    export default productResolver;

Note that you can leverage the use of TypeScript by typing the root param as StoreProductRoot:
{"base64":" ","img":{"width":1908,"height":655,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":406244,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/root-field-ts___3a10ec8a1aeba9770c7ee982995d55bc.gif"}}
  1. Open the index.ts file inside the vtex/resolvers folder and import the resolver, StoreProductResolver, you created in the previous step.
  2. Create a resolvers object that includes the imported resolvers.
    graphql/vtex/resolvers/index.ts

    _10
    import { default as StoreProductResolver } from "./product";
    _10
    _10
    const resolvers = {
    _10
    ...StoreProductResolver,
    _10
    };
    _10
    _10
    export default resolvers;

Once you have defined these files in the vtex folder, the new fields are available to use.
If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.

Adding a custom search sort

FastStore 4.9.0 and later versions can resolve extra StoreSort values. Use this procedure to sort search results by an Intelligent Search field, such as a product specification, without replacing the search resolver.
The same key must appear in three places:
  • The StoreSort extension.
  • api.customSortMap in discovery.config.js.
  • The registerCustomSortKeys call in the storefront.
The examples below use rating_desc for the GraphQL value and Rating:desc for the Intelligent Search sort string.

Requirements

Add the custom sort

Step 1 - Extend the StoreSort enum

  1. Create a .graphql file in src/graphql/vtex/typeDefs. If that folder is missing, create the VTEX API extension folders first.
  2. Add the new enum value. This extension does not need a resolver. FastStore resolves the value through customSortMap.
    src/graphql/vtex/typeDefs/sort.graphql

    _10
    extend enum StoreSort {
    _10
    rating_desc
    _10
    }

Step 2 - Map the value in discovery.config.js

  1. Open discovery.config.js.
  2. Add the same key under api.customSortMap. The mapped value is the Intelligent Search sort string (Field:asc or Field:desc).
    discovery.config.js

    _10
    module.exports = {
    _10
    api: {
    _10
    customSortMap: {
    _10
    rating_desc: "Rating:desc",
    _10
    },
    _10
    },
    _10
    };

FastStore checks customSortMap before the built-in sort values. A key in this map overrides the default mapping for that key. See api.customSortMap.

Step 3 - Accept the sort key from the URL

parseSearchState rejects a sort query parameter outside the built-in values until the storefront adds that key with registerCustomSortKeys. Call the function when a module that loads with the search page is evaluated, before parseSearchState reads the URL. A deep link or a page refresh that includes ?sort=rating_desc then keeps the custom sort.

_10
import { registerCustomSortKeys } from '@faststore/sdk'
_10
_10
registerCustomSortKeys(['rating_desc'])

The key must match the enum value and the customSortMap entry exactly. See registerCustomSortKeys.

Step 4 - Add the option to the sort control

The built-in Product Gallery sort control renders the default StoreSort values. A key that exists only in customSortMap does not appear in that control. Override SortSkeleton in the ProductGallery section and render a control that includes the custom key. Follow Overriding a native component.
Use the same key as the option value, then apply it with setSort from useSearch:

_37
import { registerCustomSortKeys, useSearch } from '@faststore/sdk'
_37
_37
registerCustomSortKeys(['rating_desc'])
_37
_37
const keyMap = {
_37
score_desc: 'Relevance',
_37
price_desc: 'Price, descending',
_37
price_asc: 'Price, ascending',
_37
orders_desc: 'Top sales',
_37
name_asc: 'Name, A-Z',
_37
name_desc: 'Name, Z-A',
_37
release_desc: 'Release date',
_37
discount_desc: 'Discount',
_37
rating_desc: 'Rating, descending',
_37
}
_37
_37
const keys = Object.keys(keyMap)
_37
_37
function CustomSort() {
_37
const {
_37
setSort,
_37
state: { sort },
_37
} = useSearch()
_37
_37
return (
_37
<select
_37
onChange={(event) => setSort(keys[event.target.selectedIndex])}
_37
value={sort}
_37
>
_37
{keys.map((key) => (
_37
<option key={key} value={key}>
_37
{keyMap[key]}
_37
</option>
_37
))}
_37
</select>
_37
)
_37
}

Confirm the query

After the enum, the map, and the storefront key are in place, query the custom value directly:

_11
query {
_11
search(first: 10, sort: rating_desc, term: "sneakers") {
_11
products {
_11
edges {
_11
node {
_11
name
_11
}
_11
}
_11
}
_11
}
_11
}

Unmapped values

A StoreSort value missing from customSortMap and from the built-in map returns a bad request with the message Unknown sort value. Keys inherited from Object.prototype, such as constructor, are rejected the same way.

Extending FastStore API with third-party API schemas

As stores grow, so does the possibility of consuming new data that is not provided by default in the FastStore API or other VTEX APIs. This means your FastStore website may need to consume new data from third-party APIs.

Instructions

Step 1 - Preparing the folders and files

If you already have the directory structure created in the Extending VTEX API schemas, add the thirdParty folder inside src/graphql.
  1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:

    _10
    mkdir graphql

  2. Inside the new graphql folder, create the thirdParty subfolder.

    _10
    mkdir thirdParty

  3. In thirdParty, create resolvers and typeDefs subfolders.

    _10
    mkdir resolvers typeDefs

    The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs paths are mandatory, but you can organize the files inside those directories as you wish.
  4. Create a index.ts file inside the resolvers folder.
    Once you have created the essentials folders, you will have a folder structure similiar to the the following:

    _11
    starter.store/
    _11
    └── src/
    _11
    └── graphql/
    _11
    ├── thirdParty/
    _11
    │ ├── resolvers/
    _11
    │ └── index.ts
    _11
    │ └── <resolverName>.ts
    _11
    │ └── …
    _11
    │ ├── typeDefs/
    _11
    │ └── <typeName>.graphql
    _11
    │ └── …

    This directory structure distinguishes between data originating from VTEX and data from third-party APIs.

Step 2 - Creating type definitions and resolvers

  1. Create a new <typeName>.graphql inside the thirdParty folder. As we are creating new queries, the name of the file that defines the type definitions can be extra.graphql.
  2. Create a new <resolver>.ts file inside the graphql/thirdParty/resolvers folder.

Step 3 - Creating query or mutation schemas

When developing a third-party extension, it's essential to create a Query or Mutation schema. This schema is crucial for generating new query entry points to access data. Below, you'll find a code example for implementing a third-party extension.
  1. Create the extra.graphql file inside the graphql/thirdParty/typeDefs folder. The extra.graphql defines the type definitions in a GraphQL schema file.
    graphql/thirdParty/typeDefs/extra.graphql

    _12
    _12
    type ExtraData {
    _12
    """
    _12
    Data customizing ExtraData
    _12
    """
    _12
    data: String!
    _12
    }
    _12
    _12
    type Query {
    _12
    extraData: ExtraData
    _12
    namedExtraData(name: String!): ExtraData
    _12
    }

  2. Create the extra.ts file inside the graphql/thirdParty/resolvers folder. This file defines the resolvers that handle the logic for the defined queries or mutations.
    graphql/thirdParty/resolvers/extra.ts

    _16
    const extraDataResolver = {
    _16
    Query: {
    _16
    extraData: () => {
    _16
    return {
    _16
    data: "Extra data",
    _16
    };
    _16
    },
    _16
    namedExtraData: (_, { name }) => {
    _16
    return {
    _16
    data: `Named extra data: ${name}`,
    _16
    };
    _16
    },
    _16
    },
    _16
    };
    _16
    _16
    export default extraDataResolver;

  3. In the graphql/thirdParty/resolvers folder, create the index.ts file to combine all the resolvers into a single object.
    graphql/thirdParty/resolvers/index.ts

    _10
    import { default as StoreExtraResolver } from "./extra";
    _10
    _10
    const resolvers = {
    _10
    ...StoreExtraResolver,
    _10
    };
    _10
    _10
    export default resolvers;

  4. With the schema and resolvers in place, query the data using GraphQL queries. Here's an example query to access the extra data:

    _10
    query {
    _10
    extraData {
    _10
    data
    _10
    }
    _10
    namedExtraData(name: "Hello") {
    _10
    data
    _10
    }
    _10
    }

Once you have defined these files in the thirdParty folder, you can query the specified data.
If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.