[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides faststore getting started setting up the headless cms in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-overview)

[1\. Setting up your environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-1-setting-up-your-environment)

[2\. Starting a new FastStore project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-2-starting-the-project)

[3\. Running the project locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-3-running-the-project-locally)

[4\. Understanding the project structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-4-understanding-the-project-structure)

[5\. Integrating your project with the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-5-integrating-your-project-with-the-headless-cms)

[Setting up the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms)

[Structuring Content Types and Sections](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-structuring-content-types-and-sections)

[Promoting your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-promoting-your-headless-cms-changes)

[6\. Next steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-6-next-steps)

[Glossary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-glossary)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/webops-dashboard)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/headless-cms-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-overview)

[1\. Setting up your environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-1-setting-up-your-environment)

[2\. Starting a new FastStore project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-2-starting-the-project)

[3\. Running the project locally](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-3-running-the-project-locally)

[4\. Understanding the project structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-4-understanding-the-project-structure)

[5\. Integrating your project with the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-5-integrating-your-project-with-the-headless-cms)

[Setting up the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms)

[Structuring Content Types and Sections](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-structuring-content-types-and-sections)

[Promoting your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-promoting-your-headless-cms-changes)

[6\. Next steps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-6-next-steps)

[Glossary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-glossary)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/webops-dashboard)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/headless-cms-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/storefront-best-practices)

---

[Storefront development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/storefront-development)

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-overview)

[5\. Integrating your project with the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-5-integrating-your-project-with-the-headless-cms)

Setting up the Headless CMS

Define your first Content Type and sync it with Headless CMS to make it available for editing in VTEX Admin.

Now that [Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-overview) is integrated with your FastStore project, you'll define your own **Content Types** and **Sections** so editors can create and manage pages in the VTEX Admin.

## What you'll accomplish

By the end of this step, you will have:

* Created the CMS folder structure in your project for content type definitions
* Defined your first Content Type (Landing Page) with SEO settings
* Synced your CMS definitions to the Headless CMS app
* Verified that your Content Type appears in the Headless CMS interface

This establishes the foundation for content editing workflows. In the next step, you'll learn to structure more complex Content Types and Sections.

## Before you begin

This guide assumes you are starting without existing CMS-related files. If your project already includes `content-types.json` or `sections.json`, create only what’s missing. See [Step 1: Creating the CMS folder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-2-setting-up-the-headless-cms%23step-1-creating-the-cms-folder).

## Instructions

### Step 1: Creating the CMS folder

1. Open the terminal and change to the root directory of your FastStore project.
2. Create a new folder named `cms` at the root of your FastStore project and a subfolder named `faststore` inside the `cms` folder. Run the following command to create them:

macOS and Linux

Windows

`1

mkdir -p cms/faststore

`

1. Create the two files below inside the `faststore` folder by running the following command:

> If your project already includes the CMS-related files: `content-types.json` or `sections.json`, create only the necessary files for your project's requirements.

macOS and Linux

Windows

`1

touch cms/faststore/content-types.json cms/faststore/sections.json

`

| File name          | Description                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content-types.json | An array of JSON objects that describes the **Content Types** available for customization in the Headless CMS app.                                        |
| sections.json      | An array of JSON objects that describes the content structure of the frontend **Section** components available for customization in the Headless CMS app. |

1. Update the `sections.json` file with an empty array:

`1

echo "[]" > cms/faststore/sections.json

`

1. Open the `content-types.json` file in any code editor of your choice and add the following code:

cms/faststore/content-types.json

`1

[

2

 {

3

 "id": "landingPage",

4

 "name": "Landing Page",

5

 "configurationSchemaSets": [

6

 {

7

 "name": "Settings",

8

 "configurations": [

9

 {

10

 "name": "seo",

11

 "schema": {

12

 "title": "SEO",

13

 "description": "Search Engine Optimization options",

14

 "type": "object",

15

 "widget": {

16

 "ui:ObjectFieldTemplate": "GoogleSeoPreview"

17

 },

18

 "required": ["slug", "title", "description"],

19

 "properties": {

20

 "slug": {

21

 "title": "Path",

22

 "type": "string",

23

 "default": "/"

24

 },

25

 "title": {

26

 "title": "Default page title",

27

 "description": "Display this title when no other title is available",

28

 "type": "string",

29

 "default": "FastStore Starter"

30

 },

31

 "description": {

32

 "title": "Meta tag description",

33

 "type": "string",

34

 "default": "A beautifully designed store"

35

 },

36

 "canonical": {

37

 "title": "Canonical url for the page",

38

 "type": "string"

39

 }

40

 }

41

 }

42

 }

43

 ]

44

 }

45

 ]

46

 }

47

]

`

> Don't worry about the structure of this file for now, as we'll learn more about it later in this tutorial. However, notice that we have defined the **Custom Page** Content Type.

1. Save your changes in the `content-types.json` file.
2. Open the terminal and run `yarn dev` to enable the watch mode for the FastStore CLI. This command will monitor any changes in the project, including the new section you have created, and automatically merge it with the default sections available in [faststore/core](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/project-structure-overview%23packagejson).

### Step 2: Syncing your changes

Let's now sync the changes with the Headless CMS app and see what happens.

1. Open another terminal and log in to your VTEX account.
2. Create a new development workspace by running the following command. _Remember to replace the values between curly brackets according to your scenario_:

`1

vtex use {workspace}

`

> Use a development workspace to try your definitions of Sections and Content Types before syncing them with the VTEX `master` workspace.

1. Change to the root directory of your FastStore project.
2. Sync your changes in the `cms` folder with the Headless CMS app:

`1

yarn cms-sync

`

> If you have the `@vtex/cli-plugin-cms@1.0.7` installed, you can use the `{builderName}` argument to synchronize a specific builder: `vtex cms:sync {builderName}`.

Once your changes are synced with the Headless CMS, the terminal will show the following message:

`1

CMS synced successfully...

`

### Step 3: Checking your changes

1. Access the VTEX Admin using the workspace you created in [Step 2 - Syncing your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-2-setting-up-the-headless-cms%23step-2-syncing-your-changes) by navigating to the following path: `https://{workspace}--{account}.myvtex.com/admin`. Make sure to replace `{workspace}` with the designated workspace name and `{account}` with your VTEX account.
2. Go to **Storefront > Headless CMS**.
3. Click on **Create New**.

![{"base64":"  ","img":{"width":1170,"height":751,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":57056,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/headless-custom-page___c952670d0592c3c66202d6702af3fc17.png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/headless-custom-page___c952670d0592c3c66202d6702af3fc17.png)

You should now see the content type we created in the previous step available for use in the Headless CMS app. However, no Sections will be available yet. We'll learn more about this in the following part of this track, [Structuring Content Types and Sections](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-3-adding-content-types-and-sections).

## Next step

Now that you've created your first Content Type, learn to structure more complex Content Types and Sections: [Structuring Content Types and Sections](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-3-adding-content-types-and-sections)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F67270558%3Fv%3D4%26w=64%26q=75)](https://github.com/mariana-caetano)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/getting-started/setting-up-the-headless-cms.mdx)

[5\. Integrating your project with the Headless CMS« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-5-integrating-your-project-with-the-headless-cms)[Structuring Content Types and SectionsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-structuring-content-types-and-sections)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F67270558%3Fv%3D4%26w=64%26q=75)](https://github.com/mariana-caetano)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[What you'll accomplish](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23what-youll-accomplish)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23instructions)

[Step 1: Creating the CMS folder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-1-creating-the-cms-folder)[Step 2: Syncing your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-2-syncing-your-changes)[Step 3: Checking your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-3-checking-your-changes)

[Next step](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23next-step)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/getting-started/setting-up-the-headless-cms.mdx)

Copy page

On this page

ON THIS PAGE

[What you'll accomplish](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23what-youll-accomplish)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23instructions)

[Step 1: Creating the CMS folder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-1-creating-the-cms-folder)[Step 2: Syncing your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-2-syncing-your-changes)[Step 3: Checking your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23step-3-checking-your-changes)

[Next step](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-setting-up-the-headless-cms/docs/guides/faststore/getting-started-setting-up-the-headless-cms%23next-step)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides changes in vtex features behavior to handle pii data in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-protection-plus)

[PII Data Architecture specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/pii-data-architecture-specifications)

[Data residency](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-residency)

[Profile System integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/profile-system)

[Working with schemas in the Profile System](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/working-with-schemas-in-the-profile-system)

[Changes in VTEX features behavior to handle PII data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data)

[Limitations of the PII data architecture during closed beta](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/limitations-of-the-pii-data-architecture-during-closed-beta)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-protection-plus)

[PII Data Architecture specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/pii-data-architecture-specifications)

[Data residency](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-residency)

[Profile System integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/profile-system)

[Working with schemas in the Profile System](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/working-with-schemas-in-the-profile-system)

[Changes in VTEX features behavior to handle PII data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data)

[Limitations of the PII data architecture during closed beta](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/limitations-of-the-pii-data-architecture-during-closed-beta)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides)

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-protection-plus)

[Changes in VTEX features behavior to handle PII data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data)

Changes in VTEX features behavior to handle PII data

> **Closed beta:** [Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/data-protection-plus) is in closed beta and is only available in select regions.

> This feature is part of [VTEX Shield](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/vtex-shield--2CVk6H9eY2CBtHjtDI7BFh), meaning _additional fees may apply._
>
> If you are already a VTEX customer and want to adopt VTEX Shield for your business, please contact [Commercial Support](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/support-at-vtex--4AXsGdGHqExp9ZkiNq9eMy/3KQWGgkPOwbFTPfBxL7YwZ).
>
> If you are not yet a customer but are interested in this solution, please complete our [contact form](https://read.calvincode.net/reader?url=https://vtex.com/us-en/contact/).

This document outlines the changes in the default behavior of certain VTEX features, which apply to stores using [Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/data-protection-plus).

To handle PII data, we provide alternative approaches that are necessary to ensure data privacy best practices. As a result, some commerce features of the VTEX platform require adaptations when implemented by the store.

In this guide, you can learn about the changes you must be aware of when managing your customers' information with the [Profile System](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system).

### Promotions - Customer cluster

To set up promotions for specific customer clusters in a way that is compatible with the PII data architecture, you must use the `piiClusterExpressions` field instead of `clusterExpressions` in [Promotions and Taxes API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/promotions-and-taxes-api%23post-/api/rnb/pvt/calculatorconfiguration).

### Order Management

There are no restrictions to the use of these Order Management features for PII data architecture accounts:

* Subscriptions
* VTEX DO
* Conversation tracker
* Shipping notifications

However, API requests to `/do`, `/conversationtracker`, `/subscriptions`, and `/shipping-tracker` paths must include the query parameter `reason` in order to retrieve unmasked PII information.

#### Orders API: PII data architecture endpoints

In order to use Orders API, you should adapt your integrations to use new endpoints, for features you may already have implemented in your store, such as retrieving order information or notifying invoices. See the table below to know which endpoints need adaptation and where to find the new reference.

| **Feature**                | **Previous endpoint**                                                                                | **New endpoint (PII data architecture)**                                                                                | **Payload changed** |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| Get order                  | GET [/api/oms/orders/{orderId}](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders/-orderId-)                                                                                | GET [/api/orders/pvt/document/{orderId}](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23get-/api/orders/pvt/document/-orderId-)                                                                         | No                  |
| List orders                | GET [/api/oms/pvt/orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders)                                                                                | POST [/api/orders/extendsearch/orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23post-/api/orders/extendsearch/orders)                                                                             | Yes                 |
| Start handling order       | POST [api/oms/orders/{orderId}/start-handling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/start-handling)                                                             | POST [/api/orders/pvt/document/{orderId}/actions/start-handling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23post-/api/orders/pvt/document/-orderId-/actions/start-handling)                         | No                  |
| Cancel order               | POST [api/oms/pvt/orders/{orderId}/cancel](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/cancel)                                                                         | POST [/api/orders/pvt/document/{orderId}/cancel](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23post-/api/orders/pvt/document/-orderId-/cancel)                                                         | No                  |
| Order invoice notification | POST [api/oms/orders/{orderId}/invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice)                                                                           | POST [api/orders/pvt/document/{orderId}/invoices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23post-/api/orders/pvt/document/-orderId-/invoices)                                                      | Yes                 |
| Send payment notification  | POST [/api/oms/pvt/orders/{orderId}/payments/{paymentId}/payment-notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api/%23post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification) | POST [/api/orders/pvt/document/{orderId}/payment/{paymentId}/notify-payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23post-/api/orders/pvt/document/-orderId-/payment/-paymentId-/notify-payment) | No                  |

> To display the unmasked contact information (`contactInformation`) with the PII-compliant [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23get-/api/orders/pvt/document/-orderId-) endpoint, the `contactId` property must be provided. This property should be available in the Profile System via the [Address](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/profile-system%23get-/api/storage/profile-system/profiles/-profileId-/addresses/-addressId-).
>
> More specifically, the `shippingAttachment` of the orderForm must contain the `contactId` that the address is related to. This is sent in the request for [Add shipping address and select delivery option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23post-/api/checkout/pub/orderForm/-orderFormId-/attachments/shippingData), where `address.contactId` must match the `contactInformation[0].id`.

#### Orders Admin interface

The PII rules have also been applied to the [Orders List (Beta)](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/order-list-beta--2QTduKHAJMFIZ3BAsi6Pi) and [Order details](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/order-details-page-beta--2Y75n54Cc9VizrlG1N6ZNl) pages. The pages have been adjusted so that:

* By default, the account will see all data masked.
* Searches by name only work with the shopper's full name.
* Searches by document only work with the shopper's full document ID.

It is possible to configure PII preferences on OMS' interface of your VTEX Admin, by following these instructions:

1. Access the VTEX Admin, go to the **Orders** menu, then click **All Orders**.
2. Click an order on the list.
3. Under the Customer information card, click `PII Preferences`.
4. Select one of the following options to configure how you will view customer's PII and be audited depending on your choice: a. **On all orders:** View personal information and be audited on all orders. b. **This order only:** View PII content and be audited on this order only. c. **Hide and do not audit:** Browse orders without displaying personal information.
5. Click `Confirm`.

#### Subscriptions

The subscription feature is compatible with the PII data architecture.

However, the **Subscriptions** Admin interface displays only masked PII. If you wish to see unmasked PII, you must use the [Subscriptions v3 API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/subscriptions-api-v3) endpoints, while sending the `reason` query parameter. Learn more about [retrieving unmasked data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system%23masked-data).

### Message Center

When you edit an email template on the **Message Center** Admin interface, you can see information about the last email sent from that template, rendered as an email. Currently, all values on the JSON Data will be masked.

### Master Data - CL, AD, BK entities

In the PII data architecture, [Master Data](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw) does not have CL, AD, BK entities. There will be a new isolated system to protect those information, [Profile System](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system).

If you are integrated to Master Data API to get any of this data (CL, AD, BK entities) you will need to integrate with the new [Profile System API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system).

### Checkout

Although [Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orderform-fields) endpoints that retrieve order information use the same path, they may behave differently. Contracts are the same for masked data, but for complete data, you must include the query parameter: `reason`. Learn more about [retrieving unmasked data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system%23masked-data).

### Payments

In order to be able to view transaction logs, store users must be assigned a role with the resource `View Payments Sensitive Data`, from the `PCI Gateway` product in the License Manager. Learn more about [License Manager resources](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) and how to [Create roles](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc%23creating-a-role).

## Limitations

### Master Data

Note that **Master Data** features may be impacted in the following three aspects.

#### Triggers

At the moment, triggers are not supported by the PII platform version Profile System.

#### Orders Index

This is a legacy integration that was deprecated and it should not be used.

#### CL

Currently, Master Data custom CL fields are not supported.

### Pricing - Price tables

The [Price tables](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/creating-price-tables--58YmY2Iwggyw4WeSCGg24S%23) feature is not supported at this moment.

### Order Management

VTEX’s Order Management System is impacted on a few different aspects. See details below.

#### Call center

You must disable call center impersonation at the License Manager.

#### Orders Admin interface

The PII rules have also been applied to the [Orders List (Beta)](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/order-list-beta--2QTduKHAJMFIZ3BAsi6Pi) and [Order details](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/order-details-page-beta--2Y75n54Cc9VizrlG1N6ZNl) pages. The pages have been adjusted so that:

* By default, the account will see all data masked.
* Searches by name only work with the shopper's full name.
* Searches by document only work with the shopper's full document ID.

It is possible to configure PII preferences on OMS' interface of your VTEX Admin, by following these instructions:

1. In your VTEX Admin, in the **Orders** menu, then **All Orders**.
2. Click an order on the list.
3. Under the Customer information card, click `PII Preferences`.
4. Select one of the following options to configure how you will view customer's PII and be audited depending on your choice: a. **On all orders:** View personal information and be audited on all orders. b. **This order only:** View PII content and be audited on this order only. c. **Hide and do not audit:** Browse orders without displaying personal information.
5. Click `Confirm`.

#### Subscriptions

The subscription feature is compatible with the PII data architecture.

However, the **Subscriptions** Admin interface displays only masked PII. If you wish to see unmasked PII, you must use the [Subscriptions v3 API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/subscriptions-api-v3) endpoints, while sending the `reason` query parameter. Learn more about [retrieving unmasked data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/profile-system%23masked-data).

### Message Center

When you edit an email template on the **Message Center** Admin interface, you can see information about the last email sent from that template, rendered as an email. Currently, all values on the JSON Data will be masked.

### Gift card

The [gift card](https://read.calvincode.net/reader?url=https://help.vtex.com/en/subcategory/gift-card--3qWeS7abxCyC0G0GMq42gA%23) feature is not supported for PII platform version accounts yet.

### Customer Credit

Currently, the [Customer Credit](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/customer-credit-overview--1uIqTjWxIIIEW0COMg4uE0) feature is not supported.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/data-privacy/changes-in-vtex-features-behavior-to-handle-pii-data.md)

[Working with schemas in the Profile System« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data//docs/guides/working-with-schemas-in-the-profile-system)[Limitations of the PII data architecture during closed betaNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data//docs/guides/limitations-of-the-pii-data-architecture-during-closed-beta)

See also

[Data Protection PlusGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-protection-plus)[Data residencyGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/data-residency)[Profile System integrationGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/profile-system)[PII Data Architecture specificationsGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/pii-data-architecture-specifications)[Limitations of the PII data architecture during closed betaGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/limitations-of-the-pii-data-architecture-during-closed-beta)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

ON THIS PAGE

[Limitations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23limitations)

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23master-data)[Pricing - Price tables](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23pricing-price-tables)[Order Management](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23order-management)[Message Center](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23message-center)[Gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23gift-card)[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23customer-credit)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/data-privacy/changes-in-vtex-features-behavior-to-handle-pii-data.md)

Copy page

On this page

ON THIS PAGE

[Limitations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23limitations)

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23master-data)[Pricing - Price tables](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23pricing-price-tables)[Order Management](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23order-management)[Message Center](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23message-center)[Gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23gift-card)[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data/docs/guides/changes-in-vtex-features-behavior-to-handle-pii-data%23customer-credit)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides integrating an app with a graphql api in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-in-vtex-io)

[List of GraphQL APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-graphql-api-list)

[Developing a GraphQL API in service apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/developing-a-graphql-api-in-service-apps)

[GraphQL authorization in IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-authorization-in-io-apps)

[Integrating an app with a GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api)

[Implementing cache in GraphQL APIs for IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/implementing-cache-in-graphql-apis-for-io-apps)

[Admin GraphQL IDE](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-ide)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-in-vtex-io)

[List of GraphQL APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-graphql-api-list)

[Developing a GraphQL API in service apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/developing-a-graphql-api-in-service-apps)

[GraphQL authorization in IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-authorization-in-io-apps)

[Integrating an app with a GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api)

[Implementing cache in GraphQL APIs for IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/implementing-cache-in-graphql-apis-for-io-apps)

[Admin GraphQL IDE](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-ide)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/app-development)

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/graphql-in-vtex-io)

[Integrating an app with a GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api)

Integrating an app with a GraphQL API

Learn how to query GraphQL APIs from an app.

When developing a VTEX IO app, you may need to interact with other apps that expose GraphQL APIs, such as retrieving data or triggering actions. To do this, you must [implement a custom client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients) that handles authenticated requests to the target app.

Once registered with the VTEX IO clients pattern (`IOClients`), the client becomes available throughout your app. You can then call it directly from resolvers or middleware functions to integrate external GraphQL capabilities into your [service app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-service).

## Before you begin

Ensure you meet the technical requirements to follow this guide:

* [VTEX IO CLI is installed](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install) on your computer.
* Access to a VTEX store with a [development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace) and the Admin environment.
* Familiarity with GraphQL concepts, such as [queries](https://read.calvincode.net/reader?url=https://graphql.org/learn/queries/), [schema](https://read.calvincode.net/reader?url=https://graphql.org/learn/schema/), and [resolvers](https://read.calvincode.net/reader?url=https://graphql.org/learn/execution/).
* Experience developing in the [TypeScript](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/) language.

## Implementation

### 1\. Starting with a template

We recommend cloning a VTEX IO app template to your computer if you are developing an app from scratch. In this tutorial, we will use the [service-example](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/service-example) template. Clone the repository using the following command in a terminal:

`1

git clone https://github.com/vtex-apps/service-example

`

### 2\. Implementing your custom client

VTEX IO provides `AppGraphQLClient` as a base class for making GraphQL requests between apps. Your custom client should extend this class, specifying the target app, which exposes the GraphQL API, in the `super` constructor. In this class, you must also define the methods you want to use in your middleware functions or resolvers.

In the following example, we define a client that uses the [Messages app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages)'s `translate` query for string translations.

node/clients/translation-graphql.ts

`` 1

import { AppGraphQLClient, InstanceOptions, IOContext } from '@vtex/api'

2

3

interface TranslatePayload {

4

 indexedByFrom: { from: string; messages: object[] }[];

5

 to: string;

6

}

7

8

export default class TranslationGraphQL extends AppGraphQLClient {

9

 constructor(ctx: IOContext, options?: InstanceOptions) {

10

 super('vtex.messages@1', ctx, options)

11

 }

12

13

 public translate = (args: TranslatePayload) => {

14

 return this.graphql.query({

15

 query: `query GetTranslation($args: TranslateArgs!) {

16

 translate(args: $args)

17

 }`,

18

 variables: { args },

19

 })

20

 }

21

}

 ``

Some details about this implementation:

1. **Target app:** In the client's constructor, define the app you want to query using the format `{vendor}.{app-name}@{version}`. In this example, we use `vtex.messages@1`, specifying only the app's major version. You can also specify the exact version with minor and patch values (for example, `vtex.messages@1.0.0`). In this constructor, you can include other options in the `options` parameter, such as [authentication tokens in the headers](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens) for [authenticated queries](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/graphql-authorization-in-io-apps).
2. **Client functions:** Create functions for each query and mutation you need. This example shows a simplified implementation to call the `translate` query. To make the query, use the function `this.graphql.query` with the following arguments:
   * `query`: Insert the query here in a [template string](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template%5Fliterals) format, surrounded by backticks (`` ` ``), which allows multi-line separation and usage of variables. In this example, we declare the [GraphQL object](https://read.calvincode.net/reader?url=https://graphql.org/learn/schema/%23object-types-and-fields) `GetTranslation` and use the `$args` variable as [input](https://read.calvincode.net/reader?url=https://graphql.org/learn/schema/%23input-object-types). Notice that query variables start with the `$` symbol. You must use the same names for the queries and variables as in the schema definition. Here we use the `translate` query and the `TranslateArgs!` type for the variable `$args`. You can find the type names in the app documentation (for example, [Messages GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/messages-graphql-api)), using an [Introspection Query](https://read.calvincode.net/reader?url=https://graphql.org/learn/introspection/), or, if you have access, in the app's source code.
   * `variables`: Insert the query variables here as an object, where the property keys are the variable names in the query. In this example, `variables.args` is used as the variable `$args` in the query.

> If you want to use mutations, use the function `this.graphql.mutate` and insert the template string as the `mutate` argument's value.

### 3\. Registering the client

After you implement the client, register it in your app's list of clients. This step makes the client available in the context of your app's resolvers. To do this, open the `node/clients/index.ts` file, import your client, and add it to the `Clients` class, as shown in the following example:

node/clients/index.ts

`1

import { IOClients } from '@vtex/api'

2

3

import TranslationGraphQL from './translation-graphql'

4

5

export class Clients extends IOClients {

6

 public get translationGraphQL() {

7

 return this.getOrSet('translationGraphQL', TranslationGraphQL)

8

 }

9

}

`

### 4\. Using the client

You can now use your custom client to request the target app from your app's handler functions by accessing it via context (`ctx.clients`).

In this example, we implement a REST API to access the translation query from the Messages app.

node/middlewares/translateMessages.ts

`1

import { json } from 'co-body'

2

3

export async function translateMessages(ctx: Context, next: () => Promise<any>) {

4

 const {

5

 clients: { translationGraphQL }

6

 } = ctx

7

8

 const requestBody = await json(ctx.req)

9

 const { from, messages, to } = requestBody

10

11

 if (!from || !messages || !to) {

12

 ctx.status = 400

13

 ctx.body = { error: 'Missing required fields: from, messages, to' }

14

 return

15

 }

16

17

 const translateArgs = {

18

 indexedByFrom: [{ from, messages }],

19

 to,

20

 }

21

22

 const response = await translationGraphQL.translate(translateArgs)

23

 ctx.status = 200

24

 ctx.body = response

25

26

 await next()

27

}

`

### 5\. Defining the service route

We need to define a route, as we are implementing a REST API to access the middleware. Go to the `node/service.json` file, define a public route with the name of the middleware function, and set the path using the format `"/_v/{app-name}/{middleware-name}"`. For this implementation, we use:

node/service.json

`1

{

2

 ...

3

 "routes": {

4

 "translateMessages": {

5

 "path": "/_v/graphql-integration/translateMessages",

6

 "public": true

7

 }

8

 }

9

}

`

### 6\. Relating a route to a middleware

Update the `node/index.ts` file to relate a route to a middleware. The routes section associates the `translateMessages` route with the `translateMessages` middleware function. The `POST` method is mapped to the `translateMessages` function. We use the `POST` method as we will send the content to be translated in the request body.

Therefore, when a `POST` request is made to the previously defined `translateMessages` route, it triggers the `translateMessages` function, which, in turn, executes the `TranslationGraphQL` client's `translate` method.

node/index.ts

`1

import { translateMessages } from './middlewares/translateMessages'

2

3

export default new Service({

4

 clients,

5

 routes: {

6

 translateMessages: method({

7

 POST: translateMessages,

8

 })

9

 },

10

})

`

### 7\. Add the policies

For your app to have permission to access any external resource, you must declare the related [policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-policies) in your app's `manifest.json` file. In the case of a GraphQL API from another app, this is a role-based policy, so you must add the app name and policy name. You can find the policy name and description in the `policies.json` file from the app's source code.

Here is the role-based policy from the Messages app for its GraphQL API:

vtex.messages/policies.json

`1

[

2

 ...

3

 {

4

 "name": "graphql-translate-messages",

5

 "description": "Allows access the translation API",

6

 "statements": [

7

 {

8

 "actions": ["get", "post"],

9

 "effect": "allow",

10

 "resources": [

11

 "vrn:vtex.messages:{{region}}:{{account}}:{{workspace}}:/_v/graphql"

12

 ]

13

 }

14

 ]

15

 },

16

 ...

17

]

`

Add the policy to your app using the format `"name": "{vendor}.{app-name}:{policy-name}"`. For the Messages app example, we use:

manifest.json

`1

"policies": [

2

 {

3

 "name": "vtex.messages:graphql-translate-messages"

4

 }

5

]

`

### 8\. Link your app

To test your app, [link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) it to the VTEX platform to enable it to run and accept requests.

Open a terminal and switch to a [development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace). Then, use the `vtex link` command.

### 9\. Test your integration

With your app running, you can test the implemented integration. In our example, we implement a REST API in a service app linked to a middleware function. Therefore, we will call the endpoint that executes this function, which invokes the translation query.

Here is a cURL example to call the translation endpoint:

`1

curl --request post \

2

 --url 'https://{{workspace}}--{{accountname}}.myvtex.com/_v/graphql-integration/translateMessages' \

3

 --header 'Accept: application/json' \

4

 --header 'Content-Type: application/json' \

5

 --header 'VtexIdclientAutCookie: {{vtex-cookie}}' \

6

 --data '{"from": "en-US", "messages": [{"content": "shoe"}, {"content": "ball"}], "to": "pt-BR"}'

`

And we get the following response:

`1

{

2

 "data": {

3

 "translate": [

4

 "sapato",

5

 "bola"

6

 ]

7

 }

8

}

`

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/GraphQL/integrating-an-app-with-a-graphql-api.mdx)

[GraphQL authorization in IO apps« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api//docs/guides/graphql-authorization-in-io-apps)[Implementing cache in GraphQL APIs for IO appsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api//docs/guides/implementing-cache-in-graphql-apis-for-io-apps)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%23before-you-begin)

[Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%23implementation)

[1\. Starting with a template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%231-starting-with-a-template)[2\. Implementing your custom client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%232-implementing-your-custom-client)[3\. Registering the client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%233-registering-the-client)[4\. Using the client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%234-using-the-client)[5\. Defining the service route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%235-defining-the-service-route)[6\. Relating a route to a middleware](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%236-relating-a-route-to-a-middleware)[7\. Add the policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%237-add-the-policies)[8\. Link your app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%238-link-your-app)[9\. Test your integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%239-test-your-integration)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/GraphQL/integrating-an-app-with-a-graphql-api.mdx)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%23before-you-begin)

[Implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%23implementation)

[1\. Starting with a template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%231-starting-with-a-template)[2\. Implementing your custom client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%232-implementing-your-custom-client)[3\. Registering the client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%233-registering-the-client)[4\. Using the client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%234-using-the-client)[5\. Defining the service route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%235-defining-the-service-route)[6\. Relating a route to a middleware](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%236-relating-a-route-to-a-middleware)[7\. Add the policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%237-add-the-policies)[8\. Link your app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%238-link-your-app)[9\. Test your integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integrating-an-app-with-a-graphql-api/docs/guides/integrating-an-app-with-a-graphql-api%239-test-your-integration)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)