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

[User] How do I use the VTEX messages app? Provide documentation and configuration details.

[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/apps/vtex.messages/docs/guides)

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

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

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

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

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

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/functional-apps)

[AB Tester](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtexarg.abtester)

[Abandoned Cart Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.abandoned-cart-service)

[Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.badges)

[Broadcaster](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.broadcaster)

[Catalog Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.catalog-images)

[Checkout UI Custom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.checkout-ui-custom)

[Checkout UI Settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.checkout-ui-settings)

[Messages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages)

[Messages GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages/messages-graphql-api)

[Product Context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.product-context)

[Pickup point selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtexbr.pickup-selector)

[Rewriter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.rewriter)

[Responsive Values](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.responsive-values)

[Search GraphQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.search-graphql)

[Session Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.session-client)

[Store Icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.store-icons)

[Store Sitemap](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.store-sitemap)

[VTEX Telemarketing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.telemarketing)

[Assembly Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/assembly-options-app)

[Affiliates Program](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/affiliates-program-app)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.my-account)

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/functional-apps)

[AB Tester](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtexarg.abtester)

[Abandoned Cart Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.abandoned-cart-service)

[Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.badges)

[Broadcaster](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.broadcaster)

[Catalog Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.catalog-images)

[Checkout UI Custom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.checkout-ui-custom)

[Checkout UI Settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.checkout-ui-settings)

[Messages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages)

[Messages GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages/messages-graphql-api)

[Product Context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.product-context)

[Pickup point selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtexbr.pickup-selector)

[Rewriter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.rewriter)

[Responsive Values](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.responsive-values)

[Search GraphQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.search-graphql)

[Session Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.session-client)

[Store Icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.store-icons)

[Store Sitemap](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.store-sitemap)

[VTEX Telemarketing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.telemarketing)

[Assembly Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/assembly-options-app)

[Affiliates Program](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/affiliates-program-app)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.my-account)

---

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

---

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

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/guides/functional-apps)

Messages

Official extension

Version: 1.71.0

Latest version: 1.71.0

The Messages app is a GraphQL service that manages translations for React and GraphQL apps.

## App behavior

**Messages** aggregates all the translation services in VTEX IO. Given a message to translate, **Messages** will get the translation in the order presented below.

1. User-defined content.
2. Translations defined in the app's `/messages` folder.
3. Automatic translation system.

If a translation is not found in one step, **Messages** proceeds to the next in the list.

### Settings

The **Messages** app has some optional configurations. By default, it will translate every string to every available language.

To configure the app settings, follow these steps:

1. In the VTEX Admin, go to **Apps** \> **Extensions Hub** \> **App Management**.
2. In the list of installed apps, search for **VTEX Messages**.
3. Click `Settings` ⚙.
4. Edit the settings as wanted.
5. Click `Save`.

See the details about all the settings in the table below:

| Setting                       | Type             | Description                                                                                |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Enable User Translations      | boolean          | Enable user translations of apps' messages. Default: true.                                                                      |
| Default Language              | string           | The default language you want to fallback to. If the value is \*, all languages will be supported. Default: \*.                 |
| Supported Languages           | array of strings | List of supported languages. If the requested language is unsupported, the Messages app will translate to the default language. |
| Two Factor URL                | string           | URL to receive a token for authorizing message saves.                                                                           |
| Enable Automatic Translations | boolean          | Enable the items not translated manually on your site to be automatically translated. Default: true.                            |

## Translating a frontend app

### Requisites

To translate a frontend app, ensure you are using the [Messages builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-messages-builder) at version `1.x` and the [React builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder) at version `3.x`.

### Defining the app translations

Create a folder named `/messages` in your app's root directory. This folder will contain all translations for your app. For example, to support the Italian language, add a file called `it.json` with the following content:

`1

{

2

 "New user greeting": "Ciao"

3

}

`

This is a key-value JSON where the key is the id used in `<FormattedMessage>` of React Intl, and the value is the desired translation. Since translating all strings manually is an arduous process, we recommend using automatic translation for languages not part of your target audience.

To leverage better automatic translations, create a file called `context.json` in your `/messages` folder with the following content:

`1

{

2

 "New user greeting": "Greeting new user that logged in"

3

}

`

This file works as a translation disambiguation. For example, the Italian word "Ciao" could mean both "Hello" and "Goodbye", so the description ensures the translation is accurate.

> The `context.json` file is necessary and has to contain all translation keys.

**Best practice**: Use keys with spaces for better organization. If there is no translation to the target language for that key, the Messages app will attempt to fall back to the English translation (defined by the user or in the `en.json` file). If that fails, the key will be translated to the target language using the automatic translation system.

## Translating the response of a backend app

Translating our backend app's response can be done in two steps:

1. Write `scalar IOMessage` in the first line of the app’s `schema.graphql` file.
2. Change from `String` to `IOMessage` the data that you want to be translatable.

`IOMessage` is a built-in [GraphQL object type](https://read.calvincode.net/reader?url=https://graphql.org/learn/schema/%23object-types-and-fields) used for translatable strings. For more information, see the [IOMessage](#iomessage) section.

Suppose that you have a GraphQL app that has the following schema:

`1

type Product {

2

 id: ID

3

 name: String

4

 categories: [String]

5

}

6

7

Type Query {

8

 productById(id: ID): Product

9

}

`

To return a product with a translatable name and categories, your app's schema should be like the one below:

`1

+ scalar IOMessage

2

+

3

type Product {

4

 id: ID

5

 name: IOMessage

6

 categories: [IOMessage]

7

}

8

9

Type Query {

10

 productById(id: ID): Product

11

}

`

Now, these fields will automatically be translated into any supported language, without requiring changes to how data is returned or stored.

## Exporting custom translations

It's also possible to export custom translations to **Messages** via a custom app. This can be handy if you want to translate external API data, like the [Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/catalog-overview).

To export such configurations:

1. Create an app with [Messages builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-messages-builder) at version `1.x`.
2. Create a `/messages` folder in the app's root directory with the desired translations.

For example, if the product name "Cool Shorts" is automatically translated into Portuguese as "_Bermuda legal_", but you want to override it, create the following files in your app's `/messages` folder:

context.json

`1

{

2

 "Cool Shorts": "A clothing item (shorts) that is cool."

3

}

`

pt.json

`1

{

2

 "Cool Shorts": "Super Bermuda"

3

}

`

Now, "Cool Shorts" will be translated to "_Super Bermuda_" in Portuguese, overriding the automatic translation.

## Message API

This section provides an overview of how to work with the Messages API. For more details, see the [Messages GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/messages-graphql-api) reference.

### IOMessage

The IOMessage is an [object type](https://read.calvincode.net/reader?url=https://graphql.org/learn/schema/%23object-types-and-fields) built into our GraphQL infrastructure used for translatable strings. It has the following structure:

`1

type IOMessage {

2

 content: String!

3

 description: String

4

 from: String

5

}

`

* `content`: String that will be translated.
* `description`: Description of the context of the string.
* `from`: Source language of content.

Note that, if your GraphQL resolver returns the IOMessage object structure instead of a raw string, **Messages** would have more information allowing it to generate an even better translation. On the other hand, if your backend does not provide such info, you can return a raw string and the other parameters will be populated automatically.

### Behaviors

* The automatic translations service supports [ICU MessageFormat](https://read.calvincode.net/reader?url=http://format-message.github.io/icu-message-format-for-translators/), however each component of the message is translated independently. Therefore, the automatic translation is not optimal and it is better to have a defined translation for complex ICU messages.
* If a message has brackets (`{`), **Messages** will assume it is an ICU Message. Therefore, if a bracket is part of your string, you should escape it (`\{`).
* When trying to translate a React app message to a language that does not have a JSON file in the `/messages` folder, the **Messages** app sends the value defined in the `en.json` file to the automatic translation service. Therefore, it is a good practice to have this file in all React apps.
* When translating a message to a full locale (e.g. `pt-BR`) and the respective file (`pt-BR.json`) is not found, **Messages** will try using the JSON file with only the language (in this example, `pt.json`).

[Checkout UI Settings« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.checkout-ui-settings)[Messages GraphQL APINext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages/messages-graphql-api)

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)[Messages Graphql APIVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages@1.71.0/messages-graphql-api)

ON THIS PAGE

[App behavior](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23app-behavior)

[Settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23settings)

[Translating a frontend app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23translating-a-frontend-app)

[Requisites](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23requisites)[Defining the app translations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23defining-the-app-translations)

[Translating the response of a backend app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23translating-the-response-of-a-backend-app)

[Exporting custom translations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23exporting-custom-translations)

[Message API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23message-api)

[IOMessage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23iomessage)[Behaviors](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.messages/docs/apps/vtex.messages%23behaviors)

Was this helpful?

[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 using node 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/using-node-clients/docs/guides)

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

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

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-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/using-node-clients/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-clients/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-clients/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-clients/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-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/using-node-clients/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/graphql-in-vtex-io)

---

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

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-clients/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/managing-edition-apps)

---

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

---

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

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/troubleshooting)

---

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-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/using-node-clients/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-clients/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-clients/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-clients/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-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/using-node-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/using-node-clients/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/graphql-in-vtex-io)

---

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

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-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/using-node-clients/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/managing-edition-apps)

---

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

---

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

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/app-development-guides)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/vtex-io-documentation-clients)

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

Using Node Clients

Learn how to use Clients in your VTEX IO app for interaction with both internal and external services.

In VTEX IO Services, Node [Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients) are powerful tools that enable you to seamlessly interact with both internal and external services. These clients play a crucial role in tasks such as making API requests, fetching data, and performing various operations within your VTEX IO apps. This guide will walk you through the effective utilization of Node Clients.

For this guide, note that VTEX IO Services exports functions that receive a `context` object. These functions can be resolver functions for GraphQL fields, middlewares for an HTTP server, or event handlers. In all cases, the Service receives a `ctx` object of type [Context](https://read.calvincode.net/reader?url=https://github.com/vtex/node-vtex-api/blob/master/src/service/worker/runtime/typings.ts), and it is within `ctx.clients` where you will find your Clients.

## Before you begin

Before diving into using Clients within your VTEX IO app, ensure 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).

## Using native `@vtex/api` Clients

1. Start a new VTEX IO app using the `node` builder and open the project using your preferred code editor.
2. Open the terminal and change to your app's `node` folder.
3. Install the `@vtex/api` package by running the following command:
`1
yarn add @vtex/api
`
4. In your app's handlers and middlewares, access the desired Clients via the `ctx` object. Here's an example of accessing the `@vtex/api` native `licenseManager` Client:
`1
export const authorize = async (ctx: Context) {
2
 const { clients: { licenseManager } } = ctx
3
 ...
4
 const data = await licenseManager.canAccessResource(/*...*/)
5
}
`

## Using native `@vtex/clients` Clients

The [@vtex/clients](https://read.calvincode.net/reader?url=https://github.com/vtex/io-clients) package exports Clients, Client Factories and TypeScript typings that help you connect a VTEX IO app with VTEX Core Commerce modules.

1. Start a new VTEX IO app using the `node` builder and open the project using your preferred code editor.
2. Open the terminal and change to your app's `node` folder.
3. Install the `@vtex/api` package by running the following command:
`1
yarn add @vtex/api
`
4. Install the `@vtex/clients` package by running the following command:
`1
yarn add @vtex/clients
`
5. Check the list of VTEX IO Clients available in the `@vtex/clients` package. Refer to [List of native Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients%23list-of-native-clients) and choose whether to use a Factory or an individual Client based on your requirements.
Using individual Clients
1. Create a `node/clients/index.ts` file and import the desired Client.
`1
import { Catalog } from '@vtex/clients'
`
2. In `node/clients/index.ts`, 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 `catalog` that uses the `Catalog` class.
`1
import { IOClients } from "@vtex/api";
2
import { Catalog } from '@vtex/clients'
3

4
export class Clients extends IOClients {
5
 public get catalog() {
6
 return this.getOrSet('catalog', Catalog)
7
 }
8
}
`
3. In your app's handlers and middlewares, access the desired Clients via the `ctx` object. Here's an example of accessing the `catalog` client and its `getSkuById` method:
`1
ctx.clients.catalog.getSkuById(...)
`
Using Client Factories
1. Create a `node/clients/index.ts` file and import the desired factory. For example:
`1
import { masterDataFor } from '@vtex/clients'
`
2. Follow the instructions for each factory, using its methods to create a Client class. Refer to [Creating a Master Data CRUD app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/create-master-data-crud-app) for more information on how to use the Master Data factory.
3. In `node/clients/index.ts`, 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 `books` that uses the `BooksClient` class.
`1
import { IOClients } from "@vtex/api";
2
const BooksClient = masterDataFor<MyBookType>('books')
3

4
export class Clients extends IOClients {
5
 public get books() {
6
 return this.getOrSet('books', BooksClient)
7
 }
8
}
`
4. In your app's handlers and middlewares, access the desired Clients via the `ctx` object. Check the following example where we access the `books` client and its `save` method:
`1
ctx.clients.books.save({ name: 'Example Book' })
`

## Using custom Clients

If you have developed custom Clients for a specific need, take the following steps to use them in your VTEX IO app.

> For a practical example, you can refer to how the `StatusClient` is set up in the [service-example](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/service-example).

1. After completing the steps in the [Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients) guide, import the `Clients` class to the `node/index.ts` file.
`1
import { Clients } from "./clients";
`
2. Create or edit the `clients` object of type `ClientsConfig<Clients>` from `@vtex/api`. This code sets up the configuration for Clients available in `ctx.clients`. It specifies an `implementation` property as `Clients`, which points to the custom Clients imported in the previous step, providing access to your custom Clients and their functionality.
`1
import type { ClientsConfig } from "@vtex/api";
2

3
const clients: ClientsConfig<Clients> = {
4
 implementation: Clients,
5
 options: {
6
 default: {
7
 retries: 2,
8
 timeout: 2000,
9
 },
10
 },
11
};
`
Note that inside the `options` property, there's a `default` key with default Client options. These options include specifying the number of retries and the timeout for HTTP requests. See the [Options](#options) table for more options. All IO Clients will be initialized with these options unless otherwise specified.
3. (Optional) In the `node/index.ts` file, consider adding a type declaration to improve type safety and code clarity. This declaration helps you define the `Context` type, which is based on `ServiceContext<Clients, State>`.
`1
import type { ServiceContext } from "@vtex/api";
2

3
declare global {
4
 type Context = ServiceContext<Clients, State>;
5
}
`
4. In the `node/index.ts` file, export a new Service that defines route handlers and client options.
`1
export default new Service<Clients, State>({
2
 clients,
3
 routes: {
4
 ...
5
 },
6
})
`
> For more information on how to set up routes, refer to the [Routes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/service-path-patterns) guide.
5. Now, in your app's handlers and middlewares, use the `clients` object from the `ctx` to access your custom Client. Check the following example where we access the custom `github` Client in the `authorize` function.
`1
export const authorize = async (ctx: Context) {
2
 const { clients: { github } } = ctx
3
 ...
4
 const data = await github.getUser(/*...*/)
5
}
`

### Options

The table below provides a detailed description of the available options for configuring your custom Client:

| 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.                        |

Contributors

1

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

[Connecting to VTEX Core Commerce APIs« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients//docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)[Receiving Catalog Changes on VTEX IONext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients//docs/guides/how-to-receive-catalog-changes-on-vtex-io)

Contributors

1

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

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23before-you-begin)

[Using native @vtex/api Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-native-vtexapi-clients)

[Using native @vtex/clients Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-native-vtexclients-clients)

[Using custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-custom-clients)

[Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23options)

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/using-node-clients.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23before-you-begin)

[Using native @vtex/api Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-native-vtexapi-clients)

[Using native @vtex/clients Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-native-vtexclients-clients)

[Using custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23using-custom-clients)

[Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients/docs/guides/using-node-clients%23options)

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 the VTEX api reference punchout api API and how to use it.

[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/api-reference/punchout-api/docs/guides)

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

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

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

API Reference

Filter By

Post

Get

Put

Delete

Patch

[Anti-fraud Provider API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/antifraud-provider-protocol/)

---

[Audience API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/audience-api/)

---

[Buyer organizations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/buyer-organizations/)

---

[Budgets API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/budgets-api/)

---

[Legacy CMS Portal API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/legacy-cms-portal-api/)

---

[Card Token Vault API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/card-token-vault-api/)

---

[Catalog API - Seller Portal](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/catalog-api-seller-portal/)

---

[Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/catalog-api/)

---

[Checkout API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/checkout-api/)

---

[Customer Credit API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/customer-credit-api/)

---

[Delivery Promise Notification API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/delivery-promise-notification-api/)

---

[GiftCard API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-api/)

---

[Giftcard Provider Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-provider-protocol/)

---

[GiftCard Hub API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-hub-api/)

---

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/headless-cms-api/)

---

[Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/intelligent-search-api/)

---

[Intelligent Search Events API - Headless](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/intelligent-search-events-api-headless/)

---

[License Manager API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/license-manager-api/)

---

[Logistics API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/logistics-api/)

---

[Marketplace API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/marketplace-apis/)

---

[Marketplace Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/marketplace-protocol/)

---

[Master Data API - v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/master-data-api-v2/)

---

[Master Data API - v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/masterdata-api/)

---

[Message Center API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/message-center-api/)

---

[mTLS API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/mtls-api/)

---

[Operational Capacity API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/operational-capacity-api/)

---

[Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/orders-api/)

---

[Organization Units API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/organization-units-api/)

---

[Payment Provider Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/payment-provider-protocol/)

---

[Payments Gateway API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/payments-gateway-api/)

---

[Pick and Pack API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-api/)

---

[Pick and Pack Last Mile Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-protocol-api/)

---

[Pick and Pack Order Changes API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-order-changes-api/)

---

[Policies System API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/policies-system-api/)

---

[Pricing API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pricing-api/)

---

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pricing-hub/)

---

[Promotions & Taxes API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/promotions-and-taxes-api/)

---

[Promotions & Taxes API v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/promotions-and-taxes-api-v2/)

---

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

Punchout login

---

[Reviews and Ratings API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/reviews-and-ratings-api/)

---

[Recommendations BFF API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/recommendations-bff-api/)

---

[SKU Bindings API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/sku-bindings-api/)

---

[Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/search-api/)

---

[Session Manager API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/session-manager-api/)

---

[SSL Certificates API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/ssl-certificates-api/)

---

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

---

[Subscriptions API (v3)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/subscriptions-api-v3/)

---

[VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-ads-api/)

---

[VTEX Shipping Network API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-shipping-network-api/)

---

[VTEX Tracking APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/tracking/)

---

[VTEX DO API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-do-api/)

---

[VTEX ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-id-api/)

---

[Profile System (Data Protection Plus)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/profile-system/)

---

[Orders API - PII Data Architecture (Data Protection Plus)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/orders-api-pii-version/)

---

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

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

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

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

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

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

---

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

API Reference

Filter By

Post

Get

Put

Delete

Patch

[Anti-fraud Provider API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/antifraud-provider-protocol/)

---

[Audience API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/audience-api/)

---

[Buyer organizations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/buyer-organizations/)

---

[Budgets API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/budgets-api/)

---

[Legacy CMS Portal API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/legacy-cms-portal-api/)

---

[Card Token Vault API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/card-token-vault-api/)

---

[Catalog API - Seller Portal](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/catalog-api-seller-portal/)

---

[Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/catalog-api/)

---

[Checkout API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/checkout-api/)

---

[Customer Credit API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/customer-credit-api/)

---

[Delivery Promise Notification API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/delivery-promise-notification-api/)

---

[GiftCard API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-api/)

---

[Giftcard Provider Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-provider-protocol/)

---

[GiftCard Hub API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/giftcard-hub-api/)

---

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/headless-cms-api/)

---

[Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/intelligent-search-api/)

---

[Intelligent Search Events API - Headless](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/intelligent-search-events-api-headless/)

---

[License Manager API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/license-manager-api/)

---

[Logistics API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/logistics-api/)

---

[Marketplace API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/marketplace-apis/)

---

[Marketplace Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/marketplace-protocol/)

---

[Master Data API - v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/master-data-api-v2/)

---

[Master Data API - v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/masterdata-api/)

---

[Message Center API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/message-center-api/)

---

[mTLS API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/mtls-api/)

---

[Operational Capacity API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/operational-capacity-api/)

---

[Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/orders-api/)

---

[Organization Units API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/organization-units-api/)

---

[Payment Provider Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/payment-provider-protocol/)

---

[Payments Gateway API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/payments-gateway-api/)

---

[Pick and Pack API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-api/)

---

[Pick and Pack Last Mile Protocol API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-protocol-api/)

---

[Pick and Pack Order Changes API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pick-and-pack-order-changes-api/)

---

[Policies System API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/policies-system-api/)

---

[Pricing API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pricing-api/)

---

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/pricing-hub/)

---

[Promotions & Taxes API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/promotions-and-taxes-api/)

---

[Promotions & Taxes API v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/promotions-and-taxes-api-v2/)

---

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

Punchout login

---

[Reviews and Ratings API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/reviews-and-ratings-api/)

---

[Recommendations BFF API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/recommendations-bff-api/)

---

[SKU Bindings API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/sku-bindings-api/)

---

[Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/search-api/)

---

[Session Manager API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/session-manager-api/)

---

[SSL Certificates API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/ssl-certificates-api/)

---

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

---

[Subscriptions API (v3)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/subscriptions-api-v3/)

---

[VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-ads-api/)

---

[VTEX Shipping Network API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-shipping-network-api/)

---

[VTEX Tracking APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/tracking/)

---

[VTEX DO API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-do-api/)

---

[VTEX ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/vtex-id-api/)

---

[Profile System (Data Protection Plus)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/profile-system/)

---

[Orders API - PII Data Architecture (Data Protection Plus)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/orders-api-pii-version/)

---

[GeGet usage count for a coupon batch« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/promotions-and-taxes-api-v2%23get-/api/rnb/v2/pvt/coupon/usage-count/group/-groupingKey-)[PoStart VTEX user punchout flowNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/punchout-api/docs/api-reference/punchout-api%23post-/api/authenticator/punchout/start)

[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 vtex io documentation rendering a badge 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-rendering-a-badge/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/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-rendering-a-badge/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-rendering-a-badge/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-rendering-a-badge/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-rendering-a-badge/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-rendering-a-badge/updates/release-notes)

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-using-advanced-layouts)

[Building a Carousel using Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-building-a-carousel-using-slider-layout)

[Creating a Quickview using Modal Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-creating-a-quickview-using-modal-layout)

[Creating modals using icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-creating-modals-using-icons)

[Rendering a badge on top of a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge)

[Using Flex Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-using-flex-layout)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

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

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/app-development)

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

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/updates/release-notes)

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-using-advanced-layouts)

[Building a Carousel using Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-building-a-carousel-using-slider-layout)

[Creating a Quickview using Modal Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-creating-a-quickview-using-modal-layout)

[Creating modals using icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-creating-modals-using-icons)

[Rendering a badge on top of a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge)

[Using Flex Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-using-flex-layout)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

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

---

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

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/store-framework-using-advanced-layouts)

[Rendering a badge on top of a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge)

Rendering a badge on top of a product

To render a badge on top of a [Product Summary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-summary) component, for example, product collection on a [Shelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-shelf) block, you combine the [Product Highlights app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-highlights/) and [Stack Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-stack-layout).

![{"base64":"  ","img":{"width":1854,"height":751,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":392124,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-rendering-a-badge-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-rendering-a-badge-0.png)

## Before you begin

1. Knowledge of how the Product Summary, Product Highlights, Stack Layout, and Product collections work is required for this recipe. If you have any doubts regarding them, we strongly recommend you access their technical documentation: [Product Summary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-summary), [Product Highlights](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-highlights/), [Stack Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-stack-layout) and [Collections](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/creating-collections-beta--yJBHqNMViOAnnnq4fyOye).
2. Ensure you have already installed [VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference) on your machine.
3. Also, make sure you have as a dependency `"vtex.product-summary": "2.x"` in your theme’s `manifest.json`.

## Instructions

1. In your theme’s `manifest.json` file, add the Product Highlights app and Stack Layout as a dependency:
`1
“dependencies” : {
2
 "vtex.product-highlights": "2.x",
3
 "vtex.stack-layout": "0.x”,
4

5
}
`
2. Open a product template you desire.
3. Then, add the `stack-layout` component to the `blocks` list of the desired template, for example:
`1
{
2
"product-summary.shelf": {
3
 "children": [
4
 "stack-layout#prodsum",
5
 ]
6
 },
7
...
`
4. In the theme’s template, declare the `stack-layout` component, and add the `"product-summary-image#shelf"` and `"vtex.product-highlights@2.x:product-highlights#collection"` as its `children` to render the image and the badge, respectivetly.
`1
"stack-layout#prodsum": {
2
 "children": [
3
 "product-summary-image#shelf",
4
 "vtex.product-highlights@2.x:product-highlights#collection"
5
 ]
6
 },
`
5. Then declare the props of the children. The first is `"product-summary-image#shelf"` props, responsible for rendering the product's image.
`1

2
"product-summary-image#shelf": {
3
 "props": {
4
 "showBadge": true,
5
 "aspectRatio": "1:1",
6
 "maxHeight": 300
7
 }
8
 },
`
6. After declare the props and the children of `vtex.product-highlights@2.x:product-highlights#collection`: `product-highlight-wrapper` and `product-highlight-text`.
> The `product-highlight-text` only renders the text already defined in the **Collection** page in a store’s Admin. For more information about it, refer to [Collections articles](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/creating-collections-beta--yJBHqNMViOAnnnq4fyOye) and the [Product Highlights app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-highlights%23configuration)
`1

2
"vtex.product-highlights@2.x:product-highlights#collection": {
3
 "props": {
4
 "type": "collection"
5
 },
6
 "children": ["product-highlight-wrapper"]
7
 },
8
 "product-highlight-wrapper": {
9
 "props": {
10
 "blockClass": "collection"
11
 },
12
 "children": ["product-highlight-text"]
13
 },
14
 "product-highlight-text": {
15
 "props": {
16
 "message": "{highlightName}"
17
 }
18
 },
19
 ...
`

Once you have declared the blocks’ props, [link the app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-linking-an-app) and see the changes live at the [Development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-workspace) you are working.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/_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/guides/vtex-io/Storefront-Guides/concepts-1/vtex-io-documentation-rendering-a-badge.md)

[Creating modals using icons« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge//docs/guides/vtex-io-documentation-creating-modals-using-icons)[Using Flex LayoutNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge//docs/guides/vtex-io-documentation-using-flex-layout)

See also

[Product SummaryVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-summary)[Stack LayoutVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-stack-layout)[Linking an appApp Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-linking-an-app)[Product HighlightsVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-product-highlights)[WorkspaceApp Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-workspace)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge%23instructions)

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/Storefront-Guides/concepts-1/vtex-io-documentation-rendering-a-badge.md)

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-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge/docs/guides/vtex-io-documentation-rendering-a-badge%23instructions)

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