[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 migrating cms settings after major update 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-migrating-cms-settings-after-major-update/docs/guides)

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-styling)

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

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/docs/guides/store-framework-updating-live-stores)

[Migrating CMS settings after a Store Theme major update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)

[Installing apps on live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/troubleshooting)

---

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-styling)

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

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/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-migrating-cms-settings-after-major-update/docs/guides/store-framework-updating-live-stores)

[Migrating CMS settings after a Store Theme major update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)

[Installing apps on live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/storefront-development)

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/store-framework-updating-live-stores)

[Migrating CMS settings after a Store Theme major update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)

Migrating CMS settings after a major theme update

When making changes to the peer dependencies of your [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme) app, you may need to perform a major update. However, transitioning to a new major version of the Store Theme may lead to undesired consequences, such as losing the configured Admin page template settings.

To handle this situation, follow the steps below to migrate template settings.

> hese instructions must be followed even when downgrading to a previous major theme version, such as from 5.x to 4.x.

## Before you begin

Make sure you have the following tools installed on your machine. They facilitate interactions with the VTEX platform and enhance your development experience:

1. Install the [VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install).
2. Install GraphQL IDE by running the following command:
`1
vtex install vtex.admin-graphql-ide@3.x
`

## Instructions

1. Open the terminal and log in to your account.
2. Switch to the [**production workspace**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-production-workspace) with your latest changes, and [publish](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available%23step-2---publishing-the-new-app-version) a new major version of your Store Theme app.
3. In the **production workspace**, install the Store Theme version published in the previous steps by running the following command:
`1
vtex install {appVendor}.{appName}@{appVersion}
`
4. Open the VTEX Admin of the production workspace used in the previous steps and go to **GraphQL Admin IDE**:
`1
vtex browse admin/graphql-ide
`
5. From the **Choose an app** dropdown list, select `vtex.pages-graphql@2.x`.
6. Copy the code below and paste it into the GraphQL IDE.
`1
 mutation{
2
 updateThemeIds(from:"{appVendor}.{appName}@{oldMajor}.x", to:"{appVendor}.{appName}@{newMajor}.x")
3
}
`

> Replace only the values in curly brackets with those that apply to your scenario. Keep the `x` without replacing it with the minor and patch versions. If you do that, the mutation won't work.

1. Run the code by clicking `Execute Query` (▶).
The expected response body is:
`1
{
2
 "data": {
3
 "updateThemeIds": true
4
 }
5
}
`
2. In the VTEX Admin, go to the **Storefront** module and validate the content in its features, such as **Site Editor**, **Pages**, and **Redirects**.
3. Once you have validated your data in the **Storefront** module, [promote your workspace to master](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-promoting-a-workspace-to-master/).

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/_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-documentation-migrating-cms-settings-after-major-update.md)

[Updating live stores« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update//docs/guides/store-framework-updating-live-stores)[Installing apps on live storesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update//docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

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

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update%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-documentation-migrating-cms-settings-after-major-update.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-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update%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 digital signage 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/digital-signage/docs/guides)

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/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/digital-signage/docs/guides/synchronizing-the-catalog-with-vtex-ads)

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

[Segmenting campaigns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/segmenting-campaigns)

[Digital Signage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage)

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/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/digital-signage/docs/guides/synchronizing-the-catalog-with-vtex-ads)

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

[Segmenting campaigns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/segmenting-campaigns)

[Digital Signage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage)

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

[Digital Signage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage)

Digital Signage

Deliver Retail Media experiences in physical stores via digital signage integration.

The Digital Signage integration uses the `POST` [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-), the same request used for retrieving ads for your digital platform.

## Retrieving ads for generic screens

All ads that should be displayed will be returned. Once all ads have been displayed, the API must be called again to retrieve the next batch of items to be shown.

> 🚧 Don't display the same items twice, as display metrics will only be counted once.

Request example:

`1

{

2

 "context": "digital_signage",

3

 "session_id": "random id",

4

 "device_id": "screen identifier",

5

 "store_name": "location identifier",

6

 "placements": {

7

 "name_of_the_location_where_the_screen_is": {

8

 "size": "1080x1920",

9

 "types": ["digital_signage"],

10

 "quantity": 1

11

 }

12

 },

13

 "segmentation": [

14

 {

15

 "key": "STATE",

16

 "values": [

17

 "RJ"

18

 ]

19

 },

20

 {

21

 "key": "CITY",

22

 "values": [

23

 "Rio de Janeiro"

24

 ]

25

 },

26

 {

27

 "key": "NEIGHBOURHOOD",

28

 "values": [

29

 "Cascadura",

30

 "Madureira"

31

 ]

32

 }

33

 ]

34

}

`

## Retrieving ads during checkout at the POS

In some cases, it is possible to identify the user making a purchase, typically during the payment process at the point of sale (POS).

Once the user is identified, you can request a personalized ad for that user.

> 🚧 For segmented campaigns, an audience integration is required.

Request example:

`1

{

2

 "context": "digital_signage",

3

 "user_id": "user identifier",

4

 "session_id": "random id",

5

 "device_id": "unique screen identifier",

6

 "store_name": "unique location identifier",

7

 "placements": {

8

 "name_of_the_location_where_the_screen_is": {

9

 "size": "1080x1920",

10

 "types": ["digital_signage"],

11

 "quantity": 5

12

 }

13

 },

14

 "segmentation": [

15

 {

16

 "key": "STATE",

17

 "values": [

18

 "RJ"

19

 ]

20

 },

21

 {

22

 "key": "CITY",

23

 "values": [

24

 "Rio de Janeiro"

25

 ]

26

 },

27

 {

28

 "key": "NEIGHBOURHOOD",

29

 "values": [

30

 "Cascadura",

31

 "Madureira"

32

 ]

33

 }

34

 ]

35

}

`

## Response

See the available response attributes on `POST` [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-).

Response example:

`1

{

2

 "placement_name": [

3

 {

4

 "type": "digital_signage",

5

6

 "assets": [

7

 {

8

 "type": "image|video",

9

 "url": "image URL",

10

 "duration": 30

11

 }

12

 ],

13

14

 "impression_url": "impression URL"

15

 }

16

 ]

17

}

`

Contributors

1

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

[Segmenting campaigns« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage//docs/guides/segmenting-campaigns)[Ads eventsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage//docs/guides/ads-events)

Contributors

1

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

[Retrieving ads for generic screens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23retrieving-ads-for-generic-screens)

[Retrieving ads during checkout at the POS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23retrieving-ads-during-checkout-at-the-pos)

[Response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23response)

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/retrieving-ads/digital-signage.md)

Copy page

On this page

ON THIS PAGE

[Retrieving ads for generic screens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23retrieving-ads-for-generic-screens)

[Retrieving ads during checkout at the POS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23retrieving-ads-during-checkout-at-the-pos)

[Response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/digital-signage/docs/guides/digital-signage%23response)

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 setting your apps billing model 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-setting-your-apps-billing-model/docs/guides)

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-app-store)

[Becoming a registered VTEX App Store developer](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-becoming-a-registered-vtex-app-store-developer)

[Developing an app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-developing-an-app)

[Setting your app's billing model](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model)

[Preparing your app for distribution](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-preparing-your-app-distribution)

[Submitting your app to the VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-submitting-your-app-in-the-vtex-app-store)

[Using the Docs builder to publish app documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/using-the-docs-builder-to-publish-app-documentation)

[App Store Guidelines](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-app-store)

[Becoming a registered VTEX App Store developer](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-becoming-a-registered-vtex-app-store-developer)

[Developing an app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-developing-an-app)

[Setting your app's billing model](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model)

[Preparing your app for distribution](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-preparing-your-app-distribution)

[Submitting your app to the VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-submitting-your-app-in-the-vtex-app-store)

[Using the Docs builder to publish app documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/using-the-docs-builder-to-publish-app-documentation)

[App Store Guidelines](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/app-development)

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-app-store)

[Setting your app's billing model](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model)

Setting your app's billing model

Once your app has been developed and is ready to go live, it's time to think about its distribution. In this step, you must define who will be allowed to install your app, whether your app will be paid or not, and how much it will cost if so.

When preparing your app for distribution, you must first establish if your new app will be private or public on the VTEX IO platform.

* **Private apps** can only be installed by their `vendor` account (i.e., the account responsible for the app's development and maintenance).
* **Public apps** are available to all accounts of the VTEX IO ecosystem. These apps can be charged or not.

## Setting the app as private

Take the following steps to make your app private:

1. Open your project in any code editor of your preference.
2. Open the `manifest.json` file and remove the `billingOptions` field.

Without `billingOptions`, VTEX IO will understand that the app in question should not be made available to any account other than the one specified in the `vendor` field of the `manifest.json` file.

## Setting the app as public

When making your app public available to the VTEX IO ecosystem, you must set up the `billingOptions` field in the app's [manifest.json](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest) file. In this context, you first need to define whether or not your app will be charged. For more information, please refer to the [billingOptions documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-billing-options).

> You can [contact the VTEX support team](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/opening-tickets-to-vtex-support--16yOEqpO32UQYygSmMSSAM) to get more information about the contracts and accounts that have installed your app.

### Instructions

The first step in making an app public is defining whether the app will be charged or not. Consider the following according to your scenario:

* [Setting the app as free](#setting-the-app-as-free)
* [Setting the app as charged](#setting-the-app-as-charged)

#### Setting the app as free

1. Open your app in any code editor of your preference.
2. Open the `manifest.json` file.
3. Add the `billingOptions` field to your app's `manifest.json` file and set the `type` property as `free`.
4. Set up the `support` property to provide a support channel for the app users.
5. Set up the `availableCountries` property to define in which countries the app will be available. If you want to make it available for all countries, use `*`.
`1
 "billingOptions": {
2
 "type": "free",
3
 "support": {
4
 "email": "support@com.br",
5
 "url": "https://support.com/hc/requests"
6
 },
7
 "availableCountries" : ["*"]
8
 }
`

#### Setting the app as charged

1. Open your app in any code editor of your preference.
2. Open the `manifest.json` file.
3. Create the `billingOptions` field in the app's `manifest.json` file and set the `type` property as `billable`.
4. Set up the `support` property to provide a support channel for the app users.
5. Set up the `availableCountries` property to define in which countries the app will be available. If you want to make it available for all countries, use `*`.
`1
 "billingOptions": {
2
 "type": "billable",
3
 "support": {
4
 "email": "support@com.br",
5
 "url": "https://support.com/hc/requests"
6
 },
7
 "availableCountries" : ["*"]
8
 }
`
6. Now, choose one of the following billing options and follow the procedures corresponding to your selection.
   * [**Fixed subscription**](#fixed-subscription) \- Charges a fixed subscription price per month. This billing model only allows a single subscription plan to be created for the app.
   * [**Fixed subscription + Variable rate**](#fixed-subscription--variable-rate) \- Charges a fixed subscription price plus a variable charge based on the app's usage. Apps with a variable rate are charged according to a metric value.
   * [**Variable subscription + Variable rate**](#variable-subscription--variable-rate) \- Charges a variable subscription price plus a variable rate based on the app's usage. Apps with a variable rate are charged according to a metric value.
7. Finally, if you opt for a variable-charge pricing strategy, take the steps presented in the [Registering the metrics data](#registering-the-metrics-data-only-for-apps-with-a-variable-pricing-strategy) section.

##### Fixed subscription

Establish a subscription plan for your app by setting up the `plan` property and its child properties:

* `id`: Plan identifier.
* `currency`: Currency code following the ISO.
* `price.subscription`: Subscription price. This property is of type `number` and accepts values with or without cents. Examples: `10` (10 dollars), `60.25` (60 dollars and 25 cents), `0.9` (90 cents).
Example of an app with a fixed subscription price

`1

 "billingOptions": {

2

 "type": "billable",

3

 "support": {

4

 "email": "support@com.br",

5

 "url": "https://support.com/hc/requests"

6

 },

7

 "availableCountries": ["*"],

8

 "plans": [{

9

 "id": "PlanBRL",

10

 "currency": "BRL",

11

 "price": {

12

 "subscription": 100

13

 }

14

 }]

15

 }

`

##### Fixed subscription + variable rate

1. Establish a subscription plan for your app by setting up the `plan` property and its child properties:
* `id`: Plan identifier.
* `currency`: Currency code following the ISO.
* `price.subscription`: Subscription price. This property is of type `number` and accepts values with or without cents. Examples: `10` (10 dollars), `60.25` (60 dollars and 25 cents), `0.9` (90 cents).
* `price.metrics`: An array specifying the metric's id and the ranges related to the app's usage and associated extra charge. Notice that you can set one or more metrics to calculate the variable rate.
Example of an app with a fixed subscription price plus a variable rate that considers only one metric

`1

 "billingOptions": {

2

 "type": "billable",

3

 "support": {

4

 "email": "support@com.br"

5

 },

6

 "availableCountries": ["*"],

7

 "plans": [{

8

 "id": "PlanUSD",

9

 "currency": "USD",

10

 "price": {

11

 "subscription": 50,

12

 "metrics": [{

13

 "id": "smsSent",

14

 "ranges": [{

15

 "exclusiveFrom": 0,

16

 "inclusiveTo": 2000,

17

 "multiplier": 0.07

18

 },

19

 {

20

 "exclusiveFrom": 2000,

21

 "inclusiveTo": 4000,

22

 "multiplier": 0.06

23

 },

24

 {

25

 "exclusiveFrom": 4000,

26

 "multiplier": 0.05

27

 }

28

 ]

29

 }]

30

 }

31

 }]

32

 }

`

From the previous example, we have:

* Each SMS costs `US$ 0.07` (`multiplier`) when more than `0` (`exclusiveFrom: 0`) SMSs _and_ less than or equal to `2000` (`inclusiveTo: 2000`) SMSs have already been sent.
* Each SMS costs `US$ 0.06` (`multiplier`) when more than `2000` (`exclusiveFrom: 2000`) _and_ less than or equal to `4000` (`inclusiveTo: 4000`) SMSs have already been sent.
* Each SMS costs `US$ 0.05` (`multiplier`) when more than `4000` (`exclusiveFrom: 4000`) SMSs have already been sent.

Therefore, the extra variable rate would be charged as follows:

* For 1500 SMSs = US$ 105.00 _(1500 x US$ 0.07 = US$ 105.00)_
* For 3500 SMSs = US$ 210.00 _(3500 x US$ 0.06 = US$ 210.00)_
* For 7000 SMSs = US$ 350.00 _(7000 x US$ 0.05 = US$ 350.00)_
Example of an app with a fixed subscription price plus a variable rate that considers more than one metric

`1

 "billingOptions": {

2

 "type": "billable",

3

 "support": {

4

 "url": "https://support.com/hc/requests",

5

 "email": "support@com.br",

6

 "phone": "+5521988887777"

7

 },

8

 "availableCountries": ["USA", "GBR", "BRA", "ESP"],

9

 "plans": [{

10

 "id": "PlanUSD",

11

 "currency": "USD",

12

 "price": {

13

 "subscription": 50,

14

 "metrics": [{

15

 "id": "myCredits",

16

 "ranges": [{

17

 "exclusiveFrom": 0,

18

 "multiplier": 1,

19

 "inclusiveTo": 100

20

 },

21

 {

22

 "exclusiveFrom": 100,

23

 "multiplier": 0.7

24

 }],

25

 "customUrl": "https://my.com/_v/metric/billing/info"

26

 },

27

 {

28

 "id": "myCredit2",

29

 "ranges": [{

30

 "exclusiveFrom": 0,

31

 "multiplier": 0.5

32

 }],

33

 "customUrl": "https://my.com/_v/metric/billing/info"

34

 }

35

 ]

36

 }

37

 }]

38

 }

`

##### Variable subscription + variable rate

1. Establish a subscription plan for your app by setting up the `plan` property and its child properties:
   * `id`: Plan identifier.
   * `currency`: Currency code following the ISO.
   * `price.subscription`: Subscription price. This property is of type `number` and accepts values with or without cents. Examples: `10` (10 dollars), `60.25` (60 dollars and 25 cents), `0.9` (90 cents).
   * `price.metrics`: An array specifying the metric's ID and the ranges related to the app's usage and associated extra charge. Notice that you can set one or more metrics to calculate the variable rate.
2. Repeat the previous step to create a new subscription plan. This new plan will be a new object inside the `plan` array.
Example of an app with a variable subscription and variable rate

`1

 "billingOptions": {

2

 "type": "billable",

3

 "support": {

4

 "url": "https://support.com/hc/requests",

5

 "email": "support@com.br",

6

 "phone": "+5521988887777"

7

 },

8

 "availableCountries": ["GBR", "BRA", "ESP"],

9

 "plans": [{

10

 "id": "PlanBRL",

11

 "currency": "BRL",

12

 "price": {

13

 "subscription": 50,

14

 "metrics": [{

15

 "id": "myCredits",

16

 "ranges": [{

17

 "exclusiveFrom": 0,

18

 "multiplier": 1,

19

 "inclusiveTo": 100

20

 },

21

 {

22

 "exclusiveFrom": 100,

23

 "multiplier": 0.7

24

 }

25

 ],

26

 "customUrl": "https://my.com/_v/metric/billing/info"

27

 },

28

 {

29

 "id": "myCredit2",

30

 "ranges": [{

31

 "exclusiveFrom": 0,

32

 "multiplier": 0.5

33

 }],

34

 "customUrl": "https://my.com/_v/metric/billing/info"

35

 }

36

 ]

37

 }

38

 },

39

 {

40

 "id": "PlanUSD",

41

 "currency": "USD",

42

 "price": {

43

 "subscription": 50,

44

 "metrics": [{

45

 "id": "myCredits",

46

 "ranges": [{

47

 "exclusiveFrom": 0,

48

 "multiplier": 1,

49

 "inclusiveTo": 100

50

 },

51

 {

52

 "exclusiveFrom": 100,

53

 "multiplier": 0.7

54

 }

55

 ],

56

 "customUrl": "https://my.com/_v/metric/billing/info"

57

 },

58

 {

59

 "id": "myCredit2",

60

 "ranges": [{

61

 "exclusiveFrom": 0,

62

 "multiplier": 0.5

63

 }],

64

 "customUrl": "https://my.com/_v/metric/billing/info"

65

 }

66

 ]

67

 }

68

 }

69

 ]

70

 }

`

### Registering the `metrics` data (Only for apps with a variable pricing strategy)

If you opted for a variable-charge pricing strategy, you must ensure that your metrics are being tracked and updated over time. Otherwise, users won't be charged the right amount.

1. Create the `policies` field in the app's `manifest.json` file and add the `vtex.billing:save-metrics` as its child.
2. Make a POST request to `https://app.io.vtex.com/vtex.billing/v0/{account}/{workspace}/_v/billing-metrics` with the following body:
`1
{
2
 "metric_id": "{metricId}",
3
 "value": "{metricAmount}"
4
}
`
Remember to remove the curly brackets from the endpoint and body replacing them with real values according to your own scenario.
   * `account` \- VTEX account responsible for the app development and maintenance.
   * `Workspace` \- Workspace being used for the app development.
   * `metricId` \- ID of the metric specified in the `billingOptions` field.
   * `metricAmount` \- Use of metrics for billing. For example: if your metric consists of charging for each SMS sent, the `metricAmount` should be equal to 1.
3. Create a client for the `vtex.billing` app or complement it with the `saveBillingMetric` method:
`` 1
import {AppClient, IOContext, InstanceOptions} from '@vtex/api'
2

3
const routes = {
4
 billingMetrics: `/_v/billing-metrics`,
5
}
6

7
export class BillingApp extends AppClient {
8
 public constructor(ioContext: IOContext, opts?: InstanceOptions) {
9
 super('vtex.billing@0.x', ioContext, opts)
10
 }
11

12
 public saveBillingMetric = (billingMetric: {
13
 metric_id: string
14
 value: number
15
 }) =>
16
 this.http.post(routes.billingMetrics, billingMetric, {
17
 metric: 'save-billing-metric',
18
 })
19
}
 ``
4. Call the `saveBillingMetric` method whenever you need to add a new quantity to the metric value:
`1
async function saveSMSBillingMetric(
2
 {clients: {billingApp}, vtex: {logger}}: ServiceContext<Clients>,
3
 res: SMSInfo,
4
) {
5
 try {
6
 await billingApp.saveBillingMetric({
7
 metric_id: 'smsSent', // metric_id is defined in the app's billingOptions
8
 value: 1, // value is a whole/integer number that you want to register. This is accumulative.
9
 })
10
 } catch (e) {
11
 // That was an error trying to save the metric value
12
 }
13
}
`

Now, all the specified billing metrics will be tracked and updated by the `saveBillingMetric` method.

It's worth mentioning that each time the metric is recorded, the date for each register is saved as well. This allows the system to determine which metrics will be charged within a given date frame.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F136460310%3Fv%3D4%26w=64%26q=75)](https://github.com/geisecosta)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/_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/App-Guides/vtex-app-store/vtex-io-documentation-setting-your-apps-billing-model.md)

[Developing an app« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model//docs/guides/vtex-io-documentation-developing-an-app)[Preparing your app for distributionNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model//docs/guides/vtex-io-documentation-preparing-your-app-distribution)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F136460310%3Fv%3D4%26w=64%26q=75)](https://github.com/geisecosta)

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

ON THIS PAGE

[Setting the app as private](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23setting-the-app-as-private)

[Setting the app as public](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23setting-the-app-as-public)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23instructions)[Registering the metrics data (Only for apps with a variable pricing strategy)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23registering-the-metrics-data-only-for-apps-with-a-variable-pricing-strategy)

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/App-Guides/vtex-app-store/vtex-io-documentation-setting-your-apps-billing-model.md)

Copy page

On this page

ON THIS PAGE

[Setting the app as private](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23setting-the-app-as-private)

[Setting the app as public](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23setting-the-app-as-public)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23instructions)[Registering the metrics data (Only for apps with a variable pricing strategy)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-your-apps-billing-model/docs/guides/vtex-io-documentation-setting-your-apps-billing-model%23registering-the-metrics-data-only-for-apps-with-a-variable-pricing-strategy)

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 store framework working with site editor 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/store-framework-working-with-site-editor/docs/guides)

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

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

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

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/faststore)

---

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

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-using-advanced-layouts)

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

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

[Making a custom component available in Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-making-a-custom-component-available-in-site-editor)

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/updates/release-notes)

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/faststore)

---

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

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-using-advanced-layouts)

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

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

[Making a custom component available in Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-making-a-custom-component-available-in-site-editor)

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/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/store-framework-working-with-site-editor/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/storefront-development)

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

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

Working with Site Editor

Discover how Site Editor simplifies the customization of your Store Framework storefront.

[Site Editor](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/site-editor-overview) works as a Content Management System (CMS) designed for stores developed with [Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-store-framework), reflecting the blocks defined in the [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme) of the VTEX account.

Based on the source code, the Site Editor displays an editable version of the website's storefront, enabling non-technical users to manage content as desired and modify components and their behavior through a friendly interface.

In your VTEX Admin, go to **Storefront > Site Editor** to see the main available tools.

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

Changes made in Site Editor are immediately reflected in the store, and every storefront block can have its properties changed there. For example, you can change the content of a rich text block and shelf properties, such as which collection is being shown, among other changes.

> Developers are responsible for creating components, defining the structure of the [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme), and ensuring seamless integration with Site Editor. This integration allows non-technical users to manage and update components easily, empowering store administrators to make changes to their storefronts without modifying the codebase.

Learn more in [Site Editor - Overview](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/site-editor-overview--299Dbeb9mFczUTyNQ9xPe1).

## Before you begin

### Develop your Store Theme

Make sure your store has a [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme) developed following the [Storefront](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-3) guide.

### Check the builders

Check if the builders are properly installed in your Store Theme. To use builders, you must have at least the `vtex.builder-hub@0.293.4` version installed in your account. Also, you need to specify them in the app’s `manifest.json` file. Learn more at [Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-builders).

You must have at least the following builders configured:

* [store builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-builder): Enables the development of Store Framework storefronts.
* [react builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder): Used to develop apps with [React](https://read.calvincode.net/reader?url=https://react.dev/) when your project requires customized frontend solutions.

### Create the store pages

Develop your store pages following the [Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-building-pages) guides.

### Configure your components

Set up your components following the [Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-components) guides.

## Essential concepts

It is important to understand the concept of a Content Management System (CMS) to learn how to work with Site Editor.

A Content Management System (CMS) is a tool for creating, managing, and modifying website content. VTEX offers different CMS options based on the storefront technology used to develop your site. Store Framework uses Site Editor, Legacy CMS Portal uses [Layout](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/1oN446gRGcR2s70RvBCAmj), and FastStore leverages [VTEX Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-overview).

On VTEX, these tools allow you to manage the pages that make up your store website with the autonomy to create, organize, edit, and define the entire structure of folders, files, and components to create the storefront you want.

To learn more, see [CMS - Overview](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/6OCY6S9tqBXPD5mgpbBInC).

## Guides in this section

In this section, you will find the following guides.

[Integrating a frontend app with Site EditorDiscover how to integrate a frontend app with Site Editor.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-integrating-frontend-app-with-site-editor)[Making a custom component available in Site EditorAllow component customization directly in Site Editor.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-making-a-custom-component-available-in-site-editor)[Site Editor schema examplesExplore practical schema examples for configuring custom components in Site Editor.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-site-editor-schema-examples)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/_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/store-framework-working-with-site-editor/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

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/store-framework-working-with-site-editor.md)

[Using Flex Layout« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor//docs/guides/vtex-io-documentation-using-flex-layout)[Integrating a frontend app with Site EditorNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor//docs/guides/vtex-io-documentation-integrating-frontend-app-with-site-editor)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/_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/store-framework-working-with-site-editor/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23before-you-begin)

[Develop your Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23develop-your-store-theme)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23check-the-builders)[Create the store pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23create-the-store-pages)[Configure your components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23configure-your-components)

[Essential concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23essential-concepts)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23guides-in-this-section)

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/store-framework-working-with-site-editor.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23before-you-begin)

[Develop your Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23develop-your-store-theme)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23check-the-builders)[Create the store pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23create-the-store-pages)[Configure your components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23configure-your-components)

[Essential concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23essential-concepts)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor/docs/guides/store-framework-working-with-site-editor%23guides-in-this-section)

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