[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 vtex io documentation how to create and use clients 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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

[Connecting to VTEX Core Commerce APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

[Using Clients in Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

[Connecting to VTEX Core Commerce APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

[Using Clients in Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/app-development)

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/app-development-guides)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

Developing Clients

Learn how to develop custom Clients for seamless communication with other services.

If you need to integrate your VTEX IO app with external services that aren't covered by [VTEX IO's native Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients), creating custom Clients can be a powerful solution. Custom Clients extend the functionality of VTEX IO Client types, offering benefits like caching and versioning. This guide will walk you through the process of creating custom Clients for your VTEX IO apps.

> Note that direct communication with APIs is generally discouraged in favor of implementing a dedicated Client. By creating custom Clients, you can extend the capabilities of your VTEX IO applications, enabling seamless integration with a wide range of services.

The diagram below illustrates how an app works with a Client to an external service:

Requester / eventIO appExternalserviceRequest to IO app / event listened by IO appRequest with  custom ClientResponse of  external service\[If requester\]  Response of IO appRequester / eventIO appExternalservice

As you develop your custom Client, you will define methods within it. These Client methods are functions responsible for handling the logic needed to execute specific actions. They facilitate interactions with services and APIs, managing requests and responses effectively.

Once you've created your custom Client, you can seamlessly integrate it into your VTEX IO app to execute the implemented methods. While you have the flexibility to incorporate data-handling logic within your Client's methods (e.g., field mapping or data filtering), it's essential to keep the core responsibilities of the Client well-organized.

## Before you begin

Before diving into Client development, make sure you have the following prerequisites in place:

* **VTEX IO development workspace:** Ensure you have a VTEX IO development workspace set up. For more information, refer to [Creating a Development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace).
* **TypeScript Familiarity:** This guide assumes you have a basic understanding of TypeScript, as we'll be using the `node` [Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-builders) to develop with TypeScript. For more information, refer to [TypeScript's official documentation](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/docs/).
* **Understanding of Clients:** Clients play a crucial role in facilitating interactions between your application and both external and internal services. For more information, refer to [Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients).

## Instructions

In this guide, we will create a custom Client example for communicating with GitHub APIs. We'll implement the following methods within our Client:

* `getRepo`: Fetches a GitHub repository given the owner and repository name.
* `getUser`: Retrieves GitHub user data based on a specified GitHub username.
* `createTag`: Creates a new tag on GitHub, taking into account the repository owner, repository, and tag data.
* `searchRepos`: Searches for GitHub repositories using a specified query.

### Step 1 - Setting up your VTEX IO app

1. Start a new VTEX IO app using the `node` builder and open the project using your preferred code editor.
2. Open a terminal and navigate to the `node` folder of your project.
`1
cd node
`
3. Install the `@vtex/api` and `@octokit/rest` packages by running the following command:
`1
yarn add @vtex/api @octokit/rest
`
4. Open the app's `manifest.json` file and add the necessary [Policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-policies). Policies are a set of permissions granted to an app, allowing or forbidding it to execute a given set of actions, such as making requests to an external resource. For this example, we will use the `outbound-access` policy to communicate with GitHub APIs (`api.github.com`).
manifest.json
`1
"policies": [
2
 {
3
 "name": "outbound-access",
4
 "attrs": {
5
 "host": "api.github.com",
6
 "path": "*"
7
 }
8
 },
9
]
`
> Note that incorrect policies may result in request blocking.

### Step 2 - Creating a custom Client

1. Create a folder named `clients` inside the `node` directory.
2. Create a TypeScript file for your Client in the `node/clients` directory. Choose a name that easily identifies your Client (e.g., `github.ts`).
3. Implement the TypeScript class that extends the appropriate [Client type](#client-types) from `@vtex/api`. In this example, we will create the `GithubClient`. Also, since we are communicating with GitHub's external APIs, we will use `ExternalClient`.
4. Use [InstanceOptions](#instanceoptions) as needed, configuring options such as authentication, timeout, caching, and more based on your requirements.

node/clients/github.ts

`1

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

2

import { ExternalClient } from '@vtex/api'

3

4

export default class GithubClient extends ExternalClient {

5

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

6

 super('http://api.github.com', context, {

7

 ...options,

8

 retries: 2,

9

 headers: {

10

 Accept: 'application/vnd.github.machine-man-preview+json',

11

 'x-vtex-use-https': 'true'

12

 }

13

 });

14

 }

15

16

 // Add the Client-related methods here

17

}

`

Ensure to export the Client from its module, either [default or named export](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).

### Step 3 - Implementing Client methods

Within your Client TypeScript file, implement the methods for your Client. You can leverage the methods provided by the [HttpClient](#httpclient-methods) to build your own methods. For example:

node/clients/github.ts

`` 1

import type { RestEndpointMethodTypes } from '@octokit/rest'

2

3

...

4

5

 public getRepo({ owner, repo }: GitRepo, token?: string) {

6

 return this.http.get<RestEndpointMethodTypes['repos']['get']['response']>(

7

 this.routes.repo({ owner, repo }),

8

 {

9

 metric: 'git-repo-get',

10

 headers: {

11

 ...this.options?.headers,

12

 Accept: 'application/vnd.github.nebula-preview+json',

13

 ...(token && { Authorization: `token ${token}` }),

14

 },

15

 }

16

 )

17

 }

 ``

Below we have the complete code example:

VTEX API core types:

* `IOContext`: Contains the VTEX IO context data, such as account, workspace, locale, authentication token, etc.
* [InstanceOptions](#instanceoptions): The options for configuring your `HttpClient` instance.
* `ExternalClient`: The base Client class for communicating with external APIs.

Type of the base Client that the custom Client extends from. Used to connect with external APIs.

A variable to store a map of routes for each method implemented in the Client. This structure is not mandatory, but it makes the code more readable when calling the `HttpClient` methods.

The `baseUrl` argument in `super` must be a URL starting with `http://`. For a secure connection, set the header `'x-vtex-use-https'` to `'true'`. This header changes the request to HTTPS when it leaves the VTEX infrastructure.

Configuration options for each request of this Client. It extends `AxiosRequestConfig`, adding some IO-specific options. In this example, we are setting the number of retries, the `Accept` header to indicate the desired format, and the `x-vtex-use-https` header to force the use of HTTPS.

The `metric` parameter gives a name to identify each HTTP call for analytics purposes.

The `getRaw` method retrieves additional information about the response, such as headers. The `get` method retrieves only the response body.

The query parameters are passed using this format, resulting in `?q={{query}}` being appended to the request's URL.

node/github.ts

`` 1

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

2

import { ExternalClient } from '@vtex/api'

3

import type { RestEndpointMethodTypes } from '@octokit/rest'

4

5

interface GitRepo {

6

 owner: string

7

 repo: string

8

}

9

10

export default class GithubClient extends ExternalClient {

11

 private routes = {

12

 repo: ({ owner, repo }: GitRepo) => `/repos/${owner}/${repo}`,

13

 user: ({ username }: { username: string }) => `/users/${username}`,

14

 tags: ({ owner, repo }: GitRepo) => `/repos/${owner}/${repo}/git/tags`,

15

 searchRepos: () => '/search/repositories',

16

 }

17

18

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

19

 super('http://api.github.com', context, {

20

 ...options,

21

 retries: 2,

22

 headers: {

23

 Accept: 'application/vnd.github.machine-man-preview+json',

24

 'x-vtex-use-https': 'true',

25

 },

26

 })

27

 }

28

29

 public getRepo({ owner, repo }: GitRepo, token?: string) {

30

 return this.http.get<RestEndpointMethodTypes['repos']['get']['response']>(

31

 this.routes.repo({ owner, repo }),

32

 {

33

 metric: 'git-repo-get',

34

 headers: {

35

 ...this.options?.headers,

36

 Accept: 'application/vnd.github.nebula-preview+json',

37

 ...(token && { Authorization: `token ${token}` }),

38

 },

39

 }

40

 )

41

 }

42

43

 public async getUser({ username }: { username: string }) {

44

 const response = await this.http.getRaw<

45

 RestEndpointMethodTypes['users']['getByUsername']['response']

46

 >(this.routes.user({ username }), { metric: 'git-user-get' })

47

48

 return response.data

49

 }

50

51

 public createTag(

52

 {

53

 owner,

54

 repo,

55

 ...tagData

56

 }: {

57

 owner: string

58

 repo: string

59

 } & RestEndpointMethodTypes['git']['createTag']['parameters'],

60

 token?: string

61

 ) {

62

 console.info('Tag data:', tagData)

63

64

 return this.http.post<RestEndpointMethodTypes['git']['createTag']>(

65

 this.routes.tags({ owner, repo }),

66

 tagData,

67

 {

68

 metric: 'git-create-tag',

69

 headers: {

70

 ...this.options?.headers,

71

 ...(token && { Authorization: `token ${token}` })

72

 },

73

 }

74

 )

75

 }

76

77

 public searchRepos({ query }: { query: string }) {

78

 return this.http.get<

79

 RestEndpointMethodTypes['search']['repos']['response']

80

 >(this.routes.searchRepos(), {

81

 metric: 'git-search-repos',

82

 params: { q: query },

83

 })

84

 }

85

}

 ``

### Step 4 - Exporting custom clients

Now that you've created your custom Client, you need to organize and export it for use in your VTEX IO service. Follow these steps:

1. Create an `index.ts` file in the `node/clients` folder.
2. Inside the `index.ts` file, import the custom Client you created in the previous step. For example:
`1
import GithubClient from "./github.ts";
`
3. Define a class called `Clients` that extends `IOClients`. This class is used to organize and configure your custom Clients. Within the Clients class, declare a `get` property for each of your custom Clients. This property allows you to access a specific Client by name. In our example, we've created a Client named `github` that uses the `GithubClient` class.
`1
import { IOClients } from "@vtex/api";
2
import GithubClient from "./github.ts";
3

4
export class Clients extends IOClients {
5
 public get github() {
6
 return this.getOrSet("github", GithubClient);
7
 }
8
}
`

Now that you have developed and exported your custom Client to communicate with the desired service, your Clients can be accessed and used within your VTEX IO service to perform various tasks, such as interacting with external APIs like GitHub. Learn how to use Clients effectively in the [Using Node Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients) guide.

## Client types

The [@vtex/api](https://read.calvincode.net/reader?url=https://github.com/vtex/node-vtex-api/) package provides a structured way to create Clients.

| Type             | Use case                                                         |
| ---------------- | ---------------------------------------------------------------- |
| AppClient        | Communication with other IO Services via HTTP calls.             |
| AppGraphQLClient | Communication with other IO GraphQL services.                    |
| ExternalClient   | Communication with external APIs.                                |
| JanusClient      | Communication with VTEX Core Commerce APIs through Janus Router. |
| InfraClient      | Communication with VTEX IO Infra services.                       |

Refer to the diagram below to better understand the relationship between Client types.

IOClient

http: HttpClient

constructor(context,options)

HttpClient

cacheableType: CacheType

logger: Logger

runMiddlewares: ComposedMiddleware

delete

get

getRaw

getWithBody

name: string

post

postRaw

put

putRaw

getConfig:(url: string, config?: RequestConfig)

request:(config: RequestConfig) : => Promise

getBuffer:(url: string, config?: RequestConfig) : => Promise<>

getStream:(url: string, config?: RequestConfig) : => Promise

head:(url: string, config?: RequestConfig) : => Promise>

GraphQLClient

mutate

query

constructor(http:HttpClient)

IOGraphQLClient

graphql: GraphQLClient

constructor(context,options)

AppGraphQLClient

constructor(app,context,options)

InfraClient

constructor(app, context, options, isRoot)

ExternalClient

constructor(baseURL,context,options)

JanusClient

constructor(context,options,environment)

AppClient

constructor(app,context,options)

Note that `context` is of type `IOContext` and `options` is of type [InstanceOptions](#instanceoptions).

## `InstanceOptions`

The `InstanceOptions` table below provides a detailed description of the available options for configuring your `HttpClient` instance:

| Option                        | Description                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| authType                      | Specifies the authentication type.                                                  |
| timeout                       | Sets the request timeout duration in milliseconds.                                  |
| memoryCache                   | Configures a memory cache layer for caching data.                                   |
| diskCache                     | Configures a disk cache layer for caching data.                                     |
| baseURL                       | Defines the base URL for making requests.                                           |
| retries                       | Specifies the number of times a request should be retried in case of failure.       |
| exponentialTimeoutCoefficient | Configures the coefficient for exponential timeout backoff strategy.                |
| initialBackoffDelay           | Sets the initial delay before starting exponential backoff retries in milliseconds. |
| exponentialBackoffCoefficient | Configures the coefficient for exponential backoff retries.                         |
| metrics                       | Specifies an object for accumulating metrics related to requests.                   |
| concurrency                   | Defines the maximum number of concurrent requests.                                  |
| headers                       | Sets default headers to be sent with every request.                                 |
| params                        | Sets default query string parameters to be sent with every request.                 |
| middlewares                   | Configures an array of middleware functions for request processing.                 |
| verbose                       | Enables or disables verbose logging for requests and responses.                     |
| name                          | Defines a custom name for the instance.                                             |
| serverTimings                 | Sets server timings for measuring request and response times.                       |
| httpsAgent                    | Configures the HTTPS agent for making requests over SSL/TLS.                        |

## `HttpClient` methods

Below is a table outlining the methods available in the `HttpClient` class:

| Method                                                       | Description                                                                                |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| get(url: string, config?: RequestConfig)                     | Sends an HTTP GET request. Returns only the response body.                                               |
| getRaw(url: string, config?: RequestConfig)                  | Sends an HTTP GET request. Returns all the response data.                                                |
| getWithBody(url: string, data?: any, config?: RequestConfig) | Sends an HTTP GET request with a request body.                                                           |
| getBuffer(url: string, config?: RequestConfig)               | Sends an HTTP GET request and resolves with the response data as a buffer along with the headers.        |
| getStream(url: string, config?: RequestConfig)               | Sends an HTTP GET request and resolves with the response as a readable stream (of type IncomingMessage). |
| put(url: string, data?: any, config?: RequestConfig)         | Sends an HTTP PUT request. Returns only the response body.                                               |
| putRaw(url: string, data?: any, config?: RequestConfig)      | Sends an HTTP PUT request. Returns all the response data.                                                |
| post(url: string, data?: any, config?: RequestConfig)        | Sends an HTTP POST request. Returns only the response body.                                              |
| postRaw(url: string, data?: any, config?: RequestConfig)     | Sends an HTTP POST request. Returns all the response data.                                               |
| patch(url: string, data?: any, config?: RequestConfig)       | Sends an HTTP PATCH request. Returns only the response body.                                             |
| head(url: string, config?: RequestConfig)                    | Sends an HTTP HEAD request and resolves when the request is complete.                                    |
| delete(url: string, config?: RequestConfig)                  | Sends an HTTP DELETE request.                                                                            |

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/_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/Getting-Started/back-end-development-guides/vtex-io-documentation-how-to-create-and-use-clients.mdx)

[Clients« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients//docs/guides/vtex-io-documentation-clients)[Connecting to VTEX Core Commerce APIsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients//docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/_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/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instructions)

[Step 1 - Setting up your VTEX IO app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-1-setting-up-your-vtex-io-app)[Step 2 - Creating a custom Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-2-creating-a-custom-client)[Step 3 - Implementing Client methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-3-implementing-client-methods)[Step 4 - Exporting custom clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-4-exporting-custom-clients)

[Client types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23client-types)

[InstanceOptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instanceoptions)

[HttpClient methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23httpclient-methods)

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/Getting-Started/back-end-development-guides/vtex-io-documentation-how-to-create-and-use-clients.mdx)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instructions)

[Step 1 - Setting up your VTEX IO app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-1-setting-up-your-vtex-io-app)[Step 2 - Creating a custom Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-2-creating-a-custom-client)[Step 3 - Implementing Client methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-3-implementing-client-methods)[Step 4 - Exporting custom clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-4-exporting-custom-clients)

[Client types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23client-types)

[InstanceOptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instanceoptions)

[HttpClient methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23httpclient-methods)

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] Explain troubleshooting error installing headless cms plugins on windows 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/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/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/troubleshooting/error-installing-headless-cms-plugins-on-windows/updates/release-notes)

Troubleshooting

API

---

Development

[I am getting 500 errors in VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-am-getting-500-errors-in-vtex-io-cli)

[I am getting errors with my service configuration app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-am-getting-errors-with-my-service-configuration-app)

[Issues during extending the FastStore API schema](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/issues-during-extending-the-faststore-api-schema)

[I can’t access the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/unable-to-access-headless-cms)

[I can’t install the Headless CMS plugins in my account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account)

[I can't install VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-vtex-io-cli)

[I can’t integrate my external Search Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-integrate-my-external-search-provider)

[My multi-language store is not functioning in the development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-multi-language-store-is-not-working-in-the-development-workspace)

[My store catalog does not display the price range filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-store-catalog-does-not-show-the-price-range-filter)

[My pages are taking too long to be published on Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-pages-are-taking-too-long-to-be-published-on-headless-cms)

[My store does not reflect the overrides I created](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-store-does-not-reflect-the-overrides-i-created)

[Modal Layout closes when I click a SKU](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/modal-layout-closes-when-i-click-a-sku)

[The Price in the shelf or in the search results is different from the product page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/the-price-in-the-shelf-or-in-the-search-results-is-different-from-the-product-page)

[The promotion highlight flag does not appear on the product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/the-promotion-highlight-flag-does-not-appear-on-the-product)

[vtex release CLI command returns an EBADF message](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/vtex-release-cli-command-returns-ebadf-message)

[I can't create a new workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-create-a-new-workspace)

[I can't install an app with a major other than 0.x](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-an-app-with-a-major-other-than-0x)

[I don't see my Store Theme changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-dont-see-my-store-theme-changes)

---

Store performance

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/updates/release-notes)

Troubleshooting

API

---

Development

[I am getting 500 errors in VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-am-getting-500-errors-in-vtex-io-cli)

[I am getting errors with my service configuration app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-am-getting-errors-with-my-service-configuration-app)

[Issues during extending the FastStore API schema](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/issues-during-extending-the-faststore-api-schema)

[I can’t access the Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/unable-to-access-headless-cms)

[I can’t install the Headless CMS plugins in my account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account)

[I can't install VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-vtex-io-cli)

[I can’t integrate my external Search Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-integrate-my-external-search-provider)

[My multi-language store is not functioning in the development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-multi-language-store-is-not-working-in-the-development-workspace)

[My store catalog does not display the price range filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-store-catalog-does-not-show-the-price-range-filter)

[My pages are taking too long to be published on Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-pages-are-taking-too-long-to-be-published-on-headless-cms)

[My store does not reflect the overrides I created](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/my-store-does-not-reflect-the-overrides-i-created)

[Modal Layout closes when I click a SKU](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/modal-layout-closes-when-i-click-a-sku)

[The Price in the shelf or in the search results is different from the product page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/the-price-in-the-shelf-or-in-the-search-results-is-different-from-the-product-page)

[The promotion highlight flag does not appear on the product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/the-promotion-highlight-flag-does-not-appear-on-the-product)

[vtex release CLI command returns an EBADF message](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/vtex-release-cli-command-returns-ebadf-message)

[I can't create a new workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-create-a-new-workspace)

[I can't install an app with a major other than 0.x](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-an-app-with-a-major-other-than-0x)

[I don't see my Store Theme changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-dont-see-my-store-theme-changes)

---

Store performance

---

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting)

Development

I can’t install the Headless CMS plugins in my account

Users may encounter errors related to symbolic links and node version incompatibility.

FastStore users may encounter the following errors after [installing the Headless CMS plugin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-1-configuring-the-vtex-account%23step-1-setting-up-the-command-line-environment).

| Error message                                                                                | Possible cause                                                                                | Solution                                                                                |
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error: EPERM: operation not permitted, symlink                                                                           | Your device isn’t enabled for development.                                                                        | [Enable Developer Mode in your machine](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows%23enable-developer-mode-in-your-machine) |
| error @oclif/core@1.26.2: The engine "node" is incompatible with this module. Expected version ">=14.0.0". Got "12.12.0" | The VTEX IO CLI’s node version isn’t updated. Expected version was \>=14.0.0, but the current version is 12.12.0. | [Update VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows%23update-vtex-io-cli)                                       |

## Solutions

To solve these issues, follow the instructions below:

* [Enable Developer Mode on your machine](#enable-developer-mode-on-your-machine)
* [Update VTEX IO CLI](#update-vtex-io-cli)

### Enable Developer Mode on your machine

While running the `vtex plugins install cms`, Windows users can get the following error:

`1

vtex plugins install cms

2

warning "@vtex/cli-plugin-cms > @vtex/api > apollo-server-core > apollo-graphql@0.9.5" has incorrect peer dependency "graphql@^14.2.1 || ^15.0.0".

3

Installing plugin @vtex/cli-plugin-cms... failed

4

 Error: EPERM: operation not permitted, symlink

5

 'C:\Users\LukeSkywalker\AppData\Roaming\npm\node_modules\vtex' ->

6

 'C:\Users\LukeSkywalker\AppData\Local\vtex\node_modules\vtex'

7

 Code: EPERM

`

FastStore projects rely on creating symbolic links (symlinks). To solve this error, you must enable [Developer Mode](https://read.calvincode.net/reader?url=https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development%23accessing-settings-for-developers) on your machine. Developer Mode grants the necessary permissions and privileges to use symlinks, which reduces the probability of encountering errors during development.

> Running the FastStore project as an administrator isn't recommended.

Learn how to enable Developer Mode in Microsoft's official guide [Enable your device for development](https://read.calvincode.net/reader?url=https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development%23accessing-settings-for-developers).

After enabling Developer Mode, launch Windows Terminal and run `vtex cms`. This will allow the system to create the necessary symlinks for running commands from the Headless CMS plugin.

### Update VTEX IO CLI

If you run the `vtex plugins install cms` command and get the error below, you need to update the VTEX IO CLI version you're using.

`1

vtex plugins install cms

2

error @oclif/core@1.26.2: The engine "node" is incompatible with this module. Expected version ">=14.0.0". Got "12.12.0"

3

error Found incompatible module.

4

Installing plugin @vtex/cli-plugin-cms... failed

5

 Error: yarn add @vtex/cli-plugin-cms@latest --non-interactive --mutex=file:C:\Users\barbara.celi\AppData\Local\vtex\yarn.lock --preferred-cach

`

Even if you update the `node` version on your machine, you must also keep VTEX IO CLI updated to avoid errors.

To update VTEX IO CLI, open Windows Terminal and follow these instructions:

1. Run the `vtex autoupdate` command in Windows Terminal.
2. Run the `vtex -v` command to check if the VTEX IO CLI and `node` versions are updated.
3. Run the `vtex plugins install cms` command to install the Headless CMS plugins.
4. Check if the installation of Headless CMS plugins was successful by running `vtex cms`. You should see the following:

`1

$ vtex cms

2

Syncs CMS schemas with the current workspace in use.

3

4

USAGE

5

 $ vtex cms COMMAND

6

COMMANDS

7

 cms sync Syncs CMS schemas with the current workspace in use.

`

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/troubleshooting/development/i-cant-install-the-headless-cms-plugins-in-my-account.md)

[I can’t access the Headless CMS« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/unable-to-access-headless-cms)[I can't install VTEX IO CLINext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-vtex-io-cli)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

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

ON THIS PAGE

[Solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23solutions)

[Enable Developer Mode on your machine](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23enable-developer-mode-on-your-machine)[Update VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23update-vtex-io-cli)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/troubleshooting/development/i-cant-install-the-headless-cms-plugins-in-my-account.md)

Copy page

On this page

ON THIS PAGE

[Solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23solutions)

[Enable Developer Mode on your machine](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23enable-developer-mode-on-your-machine)[Update VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/troubleshooting/error-installing-headless-cms-plugins-on-windows/docs/troubleshooting/i-cant-install-the-headless-cms-plugins-in-my-account%23update-vtex-io-cli)

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 ads events notification 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/ads-events-notification/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/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/ads-events-notification/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/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/ads-events-notification/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/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/ads-events-notification/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/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/ads-events-notification/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/vtex-ads)

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/getting-started-with-vtex-ads-api)

[Synchronizing the catalog with VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/synchronizing-the-catalog-with-vtex-ads)

[Retrieving ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/retrieving-ads)

[Ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events)

[Understanding ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/understanding-ads-events)

[Ads events notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification)

[Impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/impressions)

[Views](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/views)

[Clicks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/clicks)

[Conversion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/conversion)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/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/ads-events-notification/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/vtex-ads)

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/getting-started-with-vtex-ads-api)

[Synchronizing the catalog with VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/synchronizing-the-catalog-with-vtex-ads)

[Retrieving ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/retrieving-ads)

[Ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events)

[Understanding ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/understanding-ads-events)

[Ads events notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification)

[Impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/impressions)

[Views](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/views)

[Clicks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/clicks)

[Conversion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/conversion)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides)

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/vtex-ads)

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/getting-started-with-vtex-ads-api)

[Ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events)

[Ads events notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification)

Ads events notification

Learn how to send events like impressions, clicks, and conversions to VTEX Ads.

This guide explains how to send event notifications to VTEX Ads. You can send events in two ways:

* Through a web browser using the `sendBeacon()` API
* Server-side or through native apps using REST endpoints

> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-) request.
>
> This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not.

## Sending events via browser

For sending notifications in a web environment (browser), use the `sendBeacon()` method, as it is the most modern way to send data notifications. The advantage of using `sendBeacon()` is that the request is asynchronous, which means it doesn't block the loading of the current page nor the next page.

Response example from `POST` [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-):

`1

{

2

 "products": [

3

 {

4

 "ad_id": "4a94bc6e-7db1-425f-8430-cb4d17488b3b",

5

 "sku": "120210",

6

 "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1",

7

 "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1",

8

 },

9

 {

10

 "ad_id": "8c293205-52f4-45cf-9a01-37e7c26a5abc",

11

 "sku": "123123",

12

 "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/8c293205-52f4-45cf-9a01-37e7c26a5abc?pos=2",

13

 "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/8c293205-52f4-45cf-9a01-37e7c26a5abc?pos=2",

14

 }

15

 ],

16

 "banners": []

17

}

`

To send an impression event, for example, take the `impression_url` from the first ad and use it as follows:

`1

let user_data = {

2

 user_id: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",

3

 session_id: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499"

4

}

5

6

let beacon_url = "https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1"

7

8

var jsonBlob = new Blob([JSON.stringify(user_data)], { type: 'application/json' });

9

10

navigator.sendBeacon(beacon_url, jsonBlob);

`

## Sending events server-side or through a native app

In the cases that require sending via server-side or through a native app, make a `POST` request to the event URL, sending the user and session information in the payload.

You can use one of the following endpoints, depending on the event:

* `POST` [Track ad impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/beacon/impression/-ad%5Fid-)
* `POST` [Track ad clicks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/beacon/click/-ad%5Fid-)
* `POST` [Track ad views](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/beacon/view/-ad%5Fid-)
* `POST` [Track conversions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/beacon/conversion)

Request example:

`1

POST https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1 HTTP/1.1

2

user-agent: newtail

3

accept: application/json

4

content-type: application/json

5

6

{

7

 "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",

8

 "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499"

9

}

`

> A successful response will return HTTP status code 202 with no body.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/_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/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md)

[Understanding ads events« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification//docs/guides/understanding-ads-events)[ImpressionsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification//docs/guides/impressions)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/_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

[Sending events via browser](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification%23sending-events-via-browser)

[Sending events server-side or through a native app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification%23sending-events-server-side-or-through-a-native-app)

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 Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md)

Copy page

On this page

ON THIS PAGE

[Sending events via browser](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification%23sending-events-via-browser)

[Sending events server-side or through a native app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ads-events-notification/docs/guides/ads-events-notification%23sending-events-server-side-or-through-a-native-app)

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] Explain storefront development 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/storefront-development/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/api-reference)

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

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/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/storefront-development/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/storefront-best-practices)

---

Storefront Development

Express your brand identity creating unique storefronts.

![Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fstorefront-development.b4db45d7.png%26w=1920%26q=75)

FastStore

Build high-performance stores based on the Jamstack architecture

[Get started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore)

[Check the FastStore UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/components-index)

[Customize your storefront theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/using-themes-overview)

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

Store Framework

Leverage the VTEX IO infrastructure to build store themes using VTEX IO apps

[Get started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework)

[Build your store theme with VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-building-a-product-details-page)

[Customize your store theme's style](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization)

[Manage content with CMS - Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-site-editor)

[Legacy CMS PortalIf your store runs with the Legacy CMS Portal, we strongly recommend migrating it to FastStore or Store Framework.Learn more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/storefront-development/docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

Learn more about our resources for developers in the [Developer experience](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/developer-experience) guide.

[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=)