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

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/activity-flow)

---

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

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

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

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

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

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

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

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

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

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

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/activity-flow)

---

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

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

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

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

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

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

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

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

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

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

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

Understanding ads events

Learn how ad events are tracked, identified, and deduplicated to ensure accurate campaign measurement—covering sessions, user identification, conversion windows, and attribution rules.

## User and session identification

All Beacon requests require specific information to accurately identify and attribute events to users and their corresponding conversions. For this purpose, we use two key concepts:

### `session_id`

The `session_id` is the user's session identifier. It has a limited lifespan and helps us determine when a user transitions from an anonymous to an identified state. It also allows us to understand how many sessions a user goes through before converting.

The `session_id` is **mandatory** in all cases—even for short-lived sessions. For example, in an offline point-of-sale (POS) conversion, you can generate a random value. For web sessions, the value should match the current user session ID.

### `user_id`

The `user_id` is the unique identifier for a customer within your platform. It must remain consistent across all user touchpoints and sales channels.

This consistency enables us to track users who interact with an ad in one channel (e.g., online) and convert in another (e.g., offline).

The `user_id` can be sent with all events, but it is **required** only for conversion events, as this is the point where the customer must be identified.

## Event count and deduplication

**Impression**, **view**, and **click** events are **deduplicated** per user, per device, per ad. The table below summarizes how each type of event is deduplicated to ensure accurate tracking and prevent double counting:

| Event type     | Deduplication window    | Explanation                                                                                |
| -------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Impression** | 1 minute                | Multiple impressions of the same ad within 1 minute are counted only once.                                                                                |
| **Click**      | 1 hour                  | Repeated clicks on the same ad within 1 hour are counted only once.                                                                                |
| **Conversion** | 30 days (per order\_id) | Conversion events are always counted regardless of session or device and they don't follow deduplication rules applied to impressions and clicks. Conversion events are deduplicated based on the order\_id within a 30-day window. If a conversion with the same order\_id is received again during this period, it will not be counted again. |

### Example 1: Same session

A user clicks on an ad at 12:00 PM on day 1 and clicks on it three more times later that day. Only the first click will be counted.

On day 2, if the same user clicks on the same ad again **before 12:00 PM** (still within the same session), no new click is counted. After 12:00 PM, a new click is counted.

### Example 2: Session change

If the user changes sessions, a new event will always be counted, regardless of the time since the last interaction.

> **Conversion events are always counted**, whether or not the session has changed.

## Conversion window

The conversion window (or attribution window) defines the time frame during which a user's conversion can be attributed to an ad interaction.

We currently use two main attribution models based on ad type:

### Product ads

* **Conversion window**: 7 days
* **Trigger**: User clicks on a product ad

Tracking begins only when the user clicks on a product ad. Views alone do not initiate tracking. From the moment of the click, the ad is monitored for 7 days.

### Display or video ads

* **Conversion window**: 14 days
* **Trigger**: User views the ad

As soon as a user views a display or video ad, tracking begins and continues for 14 days. If the user makes a purchase during this period, the conversion is attributed to the ad.

Contributors

1

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/understanding-ads-events.md)

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

Contributors

1

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

ON THIS PAGE

[User and session identification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23user-and-session-identification)

[session\_id](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23sessionid)[user\_id](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23userid)

[Event count and deduplication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23event-count-and-deduplication)

[Example 1: Same session](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23example-1-same-session)[Example 2: Session change](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23example-2-session-change)

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

[Product ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23product-ads)[Display or video ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23display-or-video-ads)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/understanding-ads-events.md)

Copy page

On this page

ON THIS PAGE

[User and session identification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23user-and-session-identification)

[session\_id](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23sessionid)[user\_id](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23userid)

[Event count and deduplication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23event-count-and-deduplication)

[Example 1: Same session](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23example-1-same-session)[Example 2: Session change](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23example-2-session-change)

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

[Product ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23product-ads)[Display or video ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/understanding-ads-events/docs/guides/understanding-ads-events%23display-or-video-ads)

On this page

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


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

[User] Provide a guide on guides faststore atoms label in VTEX.

[Assistant]
Documentation

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

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

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

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

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

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

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/troubleshooting)

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

Storefront Development

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

---

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

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

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/webops-dashboard)

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

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/styling-overview)

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

[Atoms](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-overview)

[Badge](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-badge)

[Button](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-button)

[Checkbox](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-checkbox)

[Icon](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-icon)

[Input](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-input)

[Label](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label)

[Link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-link)

[List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-list)

[Loader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-loader)

[Overlay](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-overlay)

[Price](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-price)

[Radio](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-radio)

[Select](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-select)

[SROnly](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-sr-only)

[Skeleton](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-skeleton)

[Slider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-slider)

[Textarea](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-textarea)

[Molecules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/molecules-overview)

[Organisms](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/organisms-overview)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/troubleshooting-overview)

---

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

---

(Legacy) CMS Portal

---

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

---

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

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/troubleshooting)

---

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

Storefront Development

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

---

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

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

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/webops-dashboard)

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

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/styling-overview)

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

[Atoms](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-overview)

[Badge](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-badge)

[Button](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-button)

[Checkbox](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-checkbox)

[Icon](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-icon)

[Input](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-input)

[Label](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label)

[Link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-link)

[List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-list)

[Loader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-loader)

[Overlay](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-overlay)

[Price](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-price)

[Radio](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-radio)

[Select](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-select)

[SROnly](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-sr-only)

[Skeleton](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-skeleton)

[Slider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-slider)

[Textarea](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-textarea)

[Molecules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/molecules-overview)

[Organisms](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/organisms-overview)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/troubleshooting-overview)

---

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

---

(Legacy) CMS Portal

---

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

---

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

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

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

[Atoms](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-overview)

Label

Labels describe the meaning of input fields.

[ Source code](https://read.calvincode.net/reader?url=https://github.com/vtex/faststore/tree/main/packages/components/src/atoms/Label)

The `Label` component provides accessible text descriptions for form controls, helping users understand the purpose and expected input of each field. Typical use cases include:

* Describing the purpose of input fields (e.g., `Email Address`, `Password`, or `Phone Number`).
* Associating descriptive text with form elements for improved accessibility.
* Providing context for user interactions in forms and surveys.

Example

Code

Label

---

## Usage

### Import the component

`1

import { Label } from "@faststore/ui";

`

### Import styles

To apply styles, include the following in your stylesheet:

`1

@import "@faststore/ui/src/components/atoms/Label/styles.scss";

`

For details, see [Importing FastStore UI component styles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/using-themes-importing-ui-components-styles).

---

## Examples

### Label with Input

Labels are commonly used to describe input fields. Use the `htmlFor` attribute to associate the label with the [Input](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-input) component.

Example

Code

Email Address

### Label with custom attributes

You can pass additional HTML attributes to customize the label behavior.

Example

Code

Password

---

## Data attributes

You can target and override `Label` styles using the following data attributes:

`data-fs-label`

---

## Props

| Name       | Type   | Description                                                                            | Default  |
| ---------- | ------ | -------------------------------------------------------------------------------------- | -------- |
| **testId** | string | ID to find this component in testing tools (e.g.: cypress, testing library, and jest). | fs-label |

---

## Best practices

### ✅ Dos

* Use clear and concise text that accurately describes the expected input. Be specific about what information is required.
* Ensure labels remain visible at all times and are not replaced by placeholders.
* Keep label text short and to the point, avoiding unnecessary words.

### ❌ Don'ts

* Don't use placeholder text as a substitute for labels, as placeholders disappear when users start typing.
* Don't hide labels visually while keeping them only for screen readers.
* Don't use vague or generic text like "Enter value" or "Field".

Contributors

3

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

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

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/components/atoms/label.mdx)

[Input« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-input)[LinkNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-link)

Contributors

3

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

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

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

ON THIS PAGE

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23usage)

[Import the component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23import-the-component)[Import styles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23import-styles)

[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23examples)

[Label with Input](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23label-with-input)[Label with custom attributes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23label-with-custom-attributes)

[Data attributes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23data-attributes)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23props)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23best-practices)

[✅ Dos](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23-dos)[❌ Don'ts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23-donts)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/components/atoms/label.mdx)

Copy page

On this page

ON THIS PAGE

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23usage)

[Import the component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23import-the-component)[Import styles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23import-styles)

[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23examples)

[Label with Input](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23label-with-input)[Label with custom attributes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23label-with-custom-attributes)

[Data attributes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23data-attributes)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23props)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23best-practices)

[✅ Dos](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23-dos)[❌ Don'ts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/atoms-label/docs/guides/faststore/atoms-label%23-donts)

On this page

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


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

[User] Provide a guide on guides vtex io documentation internationalizing product prices 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-internationalizing-product-prices/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/getting-started-with-storefront-solutions)

---

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

---

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

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

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

Concepts

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

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

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

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

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

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/vtex-io-multi-language-stores)

[Internationalizing product prices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices)

[Disabling automatic translation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-disabling-automatic-translation)

[Translating storefront content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/storefront-content-internationalization)

[Translating Catalog content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/catalog-internationalization)

[Overwriting the Messages app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-overwriting-the-messages-app)

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

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/storefront-best-practices)

---

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

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

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

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

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

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

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/getting-started-with-storefront-solutions)

---

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

---

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

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

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

Concepts

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

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

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

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

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

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/vtex-io-multi-language-stores)

[Internationalizing product prices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices)

[Disabling automatic translation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-disabling-automatic-translation)

[Translating storefront content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/storefront-content-internationalization)

[Translating Catalog content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/catalog-internationalization)

[Overwriting the Messages app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-overwriting-the-messages-app)

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

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/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-internationalizing-product-prices/docs/guides/storefront-best-practices)

---

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

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

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

[Internationalizing product prices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices)

Internationalizing product prices

Ensure seamless global shopping experiences by adopting ISO currency codes for international users.

As you expand your business globally, it becomes essential to properly internationalize your website's content to cater to users from different locales. One crucial aspect of internationalization is to ensure that users can easily understand product prices and make purchases without confusion caused by misleading currency conversions. To accomplish this, we will adopt the following approach: for international users, we will display prices according to the ISO standard of the currency code (e.g., `USD`), while for local users, we will use the country-specific commonly used currency symbol (e.g., `$`). This flexibility in displaying product prices will help create a user-friendly shopping experience for both local and international users.

## Before you begin

Before you start the internationalization process, it's essential to understand [trade policies](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV). Trade policies contain configurations for catalog, pricing, promotions, logistics, customer segmentation, and payments for different sales strategies. If your store operates in multiple sales channels with varying settings, you need to [create a new trade policy](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/creating-a-trade-policy--563tbcL0TYKEKeOY4IAgAE) for each unique setup. Thus, before proceeding with this guide, ensure you have set up different trade policies that align with your store's operational requirements.

## Instructions

1. Access the Admin.
2. Go to **Store Settings > Channels > Trade Policies**.
3. Find the specific trade policy to which you want to apply the international pricing configurations and click the `Edit` button.
4. In the `Currency Code` field, select the currency code corresponding to the currency of the sales channel that uses this trade policy.
5. In the `Locale` field, select the locale where the sales channel is located.
6. Click `Save`.

> The `Currency Decimal Places` field is optional and should be used only when you want to overwrite the number of decimal places defined by the ISO standards.

Once you save your changes, your store will automatically recognize when a user's locale differs from the one set in the `Locale` field and display prices accordingly.

> The saved configuration will only apply to the selected trade policy. To replicate these configurations across all trade policies in your store, you must fill out the fields in each trade policy and save the changes.

Finally, let's take the following example. Imagine a retailer based in the United States with the following configurations:

* `Locale` field value: `United States (en-US)`
* `Currency Code` value: `US Dollar (USD)`

The outcome for different user groups will be as follows:

* **Local users (from the USA):** When a user's locale matches the `Locale` field (`United States (en-US)`), the currency symbol displayed for prices will be the commonly used symbol for the United States Dollar, which is `$`.
* **International users (outside the USA):** When a user's locale does not match the `Locale` field, the store will display product prices using the currency code specified in the `Currency Code` field, which is `USD`.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/_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/vtex-io-multi-language-stores/vtex-io-documentation-internationalizing-product-prices.md)

[Handling internationalization« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices//docs/guides/vtex-io-multi-language-stores)[Disabling automatic translationNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices//docs/guides/vtex-io-documentation-disabling-automatic-translation)

Contributors

1

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

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices%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/vtex-io-multi-language-stores/vtex-io-documentation-internationalizing-product-prices.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-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-internationalizing-product-prices/docs/guides/vtex-io-documentation-internationalizing-product-prices%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=)


[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 interacting with master data v1 through vtex io services 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/interacting-with-master-data-v1-through-vtex-io-services/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/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/interacting-with-master-data-v1-through-vtex-io-services/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/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/interacting-with-master-data-v1-through-vtex-io-services/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/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/interacting-with-master-data-v1-through-vtex-io-services/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-v1)

[Querying documents in Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/querying-documents-in-master-data-v1)

[Implementing newletter opt-in with Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/implementing-newsletter-opt-in-with-master-data-v1)

[Uploading files to Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/uploading-files-to-master-data-v1)

[Interacting with Master Data v1 through VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-v1)

[Querying documents in Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/querying-documents-in-master-data-v1)

[Implementing newletter opt-in with Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/implementing-newsletter-opt-in-with-master-data-v1)

[Uploading files to Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/uploading-files-to-master-data-v1)

[Interacting with Master Data v1 through VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides)

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/master-data-v1)

[Interacting with Master Data v1 through VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services)

Interacting with Master Data v1 through VTEX IO services

Setting up a service in VTEX IO to interact with Master Data v1.

This guide provides step-by-step instructions on how to create a VTEX IO [service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/developing-services-on-vtex-io) to interact with [Master Data v1](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw). This solution is recommended if you need to update Master Data v1 field values based on a trigger or whenever adding or updating a document.

Discover how to effectively leverage Master Data capabilities through your service in the upcoming sections.

## Before you begin

Make sure you meet the technical requirements to complete this project:

* Experience developing in [Typescript](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/) language.
* Having [VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install) installed.

## Step 1: Initializing the project

To begin setting up your service to interact with Master Data v1 on VTEX IO, follow these steps to initialize your project using the service-example template:

1. Open the terminal.
2. Type the command `vtex init`.
3. Select the `service-example` template.
4. Enter a folder name or use the default name, which is the same as the selected template.

## Step 2: Setting up policies

Configure permissions for your application to access Master Data by following the steps below:

1. Open the project folder in your preferred code editor.
2. Open the `manifest.json` file located at the root of the project.
3. Add the following structure to the `policies` section:
`1
{
2
 "name": "outbound-access",
3
 "attrs": {
4
 "host": "api.vtex.com",
5
 "path": "/dataentities/*"
6
 }
7
},
8
{
9
 "name": "ADMIN_DS"
10
}
`

## Step 3: Creating a client

Create a client class in TypeScript to extend the functionality of `MasterData` from the `@vtex/api` module:

1. Inside the `node` folder, create a `clients` folder if it does not exist.
2. Create a Typescript file in the `clients` folder. In this example, the file will be named `md.ts`.
3. Create a class that extends from the `MasterData` class from the `@vtex/api` module.
`1
import { MasterData } from '@vtex/api'
2
export default class MD extends MasterData {}
`
4. Modify the class to include the constructor and headers:
In this class, we will call the `constructor` and, within it, the `super` method, passing the `context` and `options` received in the `constructor` class.
`1
import { IOContext, InstanceOptions, MasterData } from '@vtex/api'
2

3
export default class MD extends MasterData {
4
 constructor(context: IOContext, options?: InstanceOptions) {
5
 super(context, {
6
 ...options,
7
 headers: {
8
 {{app-key}}
9
 {{app-token}}
10
 },
11
 })
12
 }
13
}
`
In this class, we will have access to several methods extended from the **Master Data** class, including:
| Method name                       | Description                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------------- |
| getDocument                       | Retrieves a document by its ID for a given data entity, with specified fields.                      |
| createDocument                    | Creates a new document in the specified data entity.                                                |
| createOrUpdateEntireDocument      | Creates or updates an entire document in the specified data entity.                                 |
| createOrUpdatePartialDocument     | Partially creates or updates a document in the specified data entity.                               |
| updateEntireDocument              | Updates an entire document by its ID for a given data entity.                                       |
| updatePartialDocument             | Partially updates a document by its ID for a given data entity.                                     |
| searchDocuments                   | Searches for documents in the specified data entity, with various search parameters and pagination. |
| searchDocumentsWithPaginationInfo | Searches for documents and returns data with pagination information.                                |
| scrollDocuments                   | Scrolls through documents in the specified data entity with various search parameters.              |
| deleteDocument                    | Deletes a document by its ID for a given data entity.                                               |
5. Add the desired method. The example below uses the `getDocument` method:
`1
public getDocumentById(
2
 dataEntity: string,
3
 id: string,
4
 fields: string[]
5
): Promise<any> {
6
 return this.getDocument({ dataEntity, id, fields })
7
}
`

## Step 4: Registering the Client

After creating our Client class, you need to register it in the `index.ts` file within the same `clients` folder:

1. Open the `index.ts` file in the `clients` folder.
2. Import the new client (e.g., `MD`) and add it to the `Clients` class, as exemplified below:
`1
import { IOClients } from '@vtex/api'
2
import MD from './md'
3

4
// Extend the default IOClients implementation with our own custom clients
5
export class Clients extends IOClients {
6
 public get MD() {
7
 return this.getOrSet('MD', MD)
8
 }
9
}
`

## Step 5: Creating the middleware

Implement a middleware function to handle interactions between your service and Master Data, executing the method we created and returning the response based on the context:

1. Inside the `node` folder, create a `middlewares` folder if it does not exist.
2. Create a file named `masterdataMiddleware.ts` in the `middlewares` folder.
3. Add your TypeScript code to `masterdataMiddleware.ts`.
Following the example in the previous sections to illustrate this step, in this middleware, we will return the call to the method created to a variable and then add this variable to the context body. The method expects to receive an _entity_, a _document ID_, and an _array_ of fields to be returned in the response.
`1
export async function masterdataMiddleware(
2
 ctx: Context,
3
 next: () => Promise<any>
4
) {
5
 const {
6
 clients: { MD },
7
 } = ctx
8

9
 const response = await MD.getDocumentById(
10
 'CL',
11
 '0807f150-68bb-11Ec-82ac-12fdbe358f3f',
12
 ['id', 'email']
13
 )
14

15
 ctx.status = 200
16

17
 ctx.body = {
18
 response,
19
 }
20

21
 await next()
22
}
`

## Step 6: Configuring the route

Configure a dedicated route in your service that will be accessed through your store's endpoint:

1. Open the `service.json` file in the `node` folder.
2. In the `routes` section, define the `routes` object as shown below. In this example, we will define the `path` as `/_v/md/get-document` and make this route public.
`1
"routes": {
2
 "masterdata": {
3
 "path": "/_v/md/get-document",
4
 "public": true
5
 }
6
}
`
3. Open the `index.ts` file in the `node` folder.
In this file, you will see a new instance of service created. You will register your route within the `routes` object.
4. Register the route within the `routes` object.
`1
 masterdata: method({
2
 GET: [masterdataMiddleware],
3
 }),
`

> The `masterdata` attribute is the route ID created in the `service.json` file.

The `masterdata` attribute receives a function containing an object where we can pass various middleware mappings. In this case, we will use the HTTP method **GET**, which receives an _array_ where we must declare the middleware created in previous sections.

## Step 7: Running the project

Finalize setup by linking your project to a development workspace and testing the configured service routes:

1. In the terminal, navigate to the root of the project.
2. Run the command `vtex link`.
After linking, you should see the following message:
`1
**info:** *Available service routes: https://{{workspace}}--{{accountName}}.myvtex.com/{{path}}
`
3. Access the service route from the previous step in your browser.
Following the example of a service to retrieve a document, you should see a response with the fields defined in the middleware:
`1
{
2
 "response": {
3
 "id": "0807f150-68bb-11Ec-82ac-12fdbe358f3f",
4
 "email": "john@mail.com"
5
 }
6
}
`

## Conclusion

These instructions enable you to configure clients, middleware, and routes to set up a VTEX IO service for interacting with Master Data v1\. Note that there are various methods and configurations beyond this guide to further customize and optimize your integration with VTEX IO and Master Data.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Master-Data/master-data-v1/interacting-with-master-data-v1-through-vtex-io-services.md)

[Uploading files to Master Data v1« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services//docs/guides/uploading-files-to-master-data-v1)[Configuration GuidesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services//docs/guides/payments-configuration-guides)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23before-you-begin)

[Step 1: Initializing the project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-1-initializing-the-project)

[Step 2: Setting up policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-2-setting-up-policies)

[Step 3: Creating a client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-3-creating-a-client)

[Step 4: Registering the Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-4-registering-the-client)

[Step 5: Creating the middleware](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-5-creating-the-middleware)

[Step 6: Configuring the route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-6-configuring-the-route)

[Step 7: Running the project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-7-running-the-project)

[Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23conclusion)

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/Master-Data/master-data-v1/interacting-with-master-data-v1-through-vtex-io-services.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23before-you-begin)

[Step 1: Initializing the project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-1-initializing-the-project)

[Step 2: Setting up policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-2-setting-up-policies)

[Step 3: Creating a client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-3-creating-a-client)

[Step 4: Registering the Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-4-registering-the-client)

[Step 5: Creating the middleware](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-5-creating-the-middleware)

[Step 6: Configuring the route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-6-configuring-the-route)

[Step 7: Running the project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23step-7-running-the-project)

[Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/interacting-with-master-data-v1-through-vtex-io-services/docs/guides/interacting-with-master-data-v1-through-vtex-io-services%23conclusion)

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