[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 routes 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-routes/docs/guides)

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

---

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

---

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

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

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

Concepts

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

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

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

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

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

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

[Adding custom headers to your Store Framework store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-adding-custom-headers-to-your-store-framework-store)

[Best practices for associating a custom page with a content type](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-best-practices-for-associating-a-custom-page-with-a-content-type)

[Customizing your 404 page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-customizing-your-404-page)

[Enabling 404 pages for invalid single-segment paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-enabling-404-pages-for-invalid-single-segment-paths)

[Managing URL redirects](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-managing-url-redirects)

[Using several service workers in your store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-using-several-service-workers-in-your-store)

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

---

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

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

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

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

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

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

---

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

---

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

---

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

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

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

Concepts

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

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

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

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

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

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

[Adding custom headers to your Store Framework store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-adding-custom-headers-to-your-store-framework-store)

[Best practices for associating a custom page with a content type](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-best-practices-for-associating-a-custom-page-with-a-content-type)

[Customizing your 404 page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-customizing-your-404-page)

[Enabling 404 pages for invalid single-segment paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-enabling-404-pages-for-invalid-single-segment-paths)

[Managing URL redirects](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-managing-url-redirects)

[Using several service workers in your store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/vtex-io-documentation-using-several-service-workers-in-your-store)

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

---

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

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

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

Routing

Learn how routing is managed in VTEX IO Store Framework.

A route maps a URL pattern and an HTTP request method to an action. It defines how the application responds to client requests for specific endpoints.

When using [VTEX IO Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework), you do not need to manage routing and HTTP methods directly. Instead, routing and HTTP request methods are managed by either the [Rewriter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.rewriter) app or the [store builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-builder), depending on the route type. This allows you to focus on creating and managing route paths and page templates.

In Store Framework, different apps and builder manage various types of routes. The table below outlines the primary managers for each route type:

| Route type         | Responsibility | Description                                                                                |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Product routes** | Rewriter app   | Routes related to product pages, forwarded by the Rewriter app to the rendering pipeline.                                                                                |
| **Search routes**  | Rewriter app   | Routes related to search result pages, processed and forwarded by the Rewriter app.                                                                                |
| **Catalog routes** | Rewriter app   | Custom routes for predefined templates (e.g., [department](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store/blob/master/store/routes.json%23L27), [brand](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store/blob/master/store/routes.json%23L21), and [category](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store/blob/master/store/routes.json%23L33) handled by the Rewriter app and mapped to the appropriate page. |
| **Custom routes**  | Store builder  | User-defined routes for custom landing pages or other routes that fall outside of predefined product or category routes, directly managed by the store builder and forwarded to the render server.                                                                                |

The [Rewriter app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.rewriter) interprets the requested path, identifies the route type, and then forwards the route path to the rendering pipeline. Learn more in [Rewriter GraphQL API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.rewriter@1.63.0/rewriter-graphql-api). Meanwhile, the [store builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-builder) forwards custom route paths directly to the render server. To learn how to create a custom page, see the [Creating a new custom page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-new-custom-page) guide.

In this section, you will learn how to manage routes in your Store Framework store.

## 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 [Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-3) tutorial.

### Check the builders

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

Make sure the [store builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-builder) is configured, as it enables the development of Store Framework storefronts.

### Check Rewriter installation

To check if the [Rewriter app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.rewriter) is installed in your store, follow the guide [Listing an account's apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-listing-an-accounts-apps) and search for `vtex.rewriter` in the **Installed apps** list. If it is not, install the app by following the guide [Installing an app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-an-app).

## Guides in this section

[Best practices for associating a custom page with a content typeConfigure URLs effectively when associating custom pages with content types.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-best-practices-for-associating-a-custom-page-with-a-content-type)[Enabling 404 pagesLearn how to enable and configure 404 error pages for better user experience.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-enabling-404-pages)[Managing URL redirectsDiscover how to manage URL redirects to ensure seamless navigation.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-managing-url-redirects)[Using several service workers in your storeExplore how to use multiple service workers to enhance your store’s performance and offline capabilities.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-several-service-workers-in-your-store)

Contributors

1

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

[Overwriting the Messages app« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes//docs/guides/vtex-io-documentation-overwriting-the-messages-app)[Adding custom headers to your Store Framework storeNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes//docs/guides/vtex-io-documentation-adding-custom-headers-to-your-store-framework-store)

Contributors

1

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

[Develop your Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23develop-your-store-theme)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23check-the-builders)[Check Rewriter installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23check-rewriter-installation)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%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-routing.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-routes/docs/guides/store-framework-routing%23before-you-begin)

[Develop your Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23develop-your-store-theme)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23check-the-builders)[Check Rewriter installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%23check-rewriter-installation)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-routes/docs/guides/store-framework-routing%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=)


[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 headless commerce 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/headless-commerce/docs/guides)

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce)

[Headless catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-catalog)

[Headless cart and checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-cart-and-checkout)

[Headless profile management and order history](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-profile-management-and-order-history)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/tax-service-integration-guide)

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

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/recaptcha)

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce)

[Headless catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-catalog)

[Headless cart and checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-cart-and-checkout)

[Headless profile management and order history](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-profile-management-and-order-history)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/tax-service-integration-guide)

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

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/recaptcha)

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

Integration Guides

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce)

Headless commerce

VTEX technology allows for flexibility, enabling our clients to build commerce experiences that address their needs and potentialize their strengths.

This guide can help you leverage VTEX APIs to build a headless shopping experience considering that you:

* Will use VTEX core commerce features via REST APIs.
* Will use the native VTEX ID page to [authenticate shoppers](#authentication).
* Can build your storefront using a third-party Content Management System (CMS), instead of VTEX storefront solutions, except for the authentication page.
* Can use VTEX IO to host core commerce microservices and any developed applications to extend functionality.

![{"base64":"  ","img":{"width":4636,"height":3450,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":809205,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/headless-commerce/headless-integration.jpg"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/headless-commerce/headless-integration.jpg)

> This document outlines the basic features required to deliver any shopping experience and does not limit the VTEX capabilities you can use. You are free to use any VTEX features that benefit your store, even if they are not mentioned above.

## Authentication

When it comes to authentication, a headless store must consider two aspects:

* [Authenticating shopper identity](#authenticating-shopper-identity)
* [Authenticating requests to VTEX APIs](#authenticating-requests-to-vtex-apis)

> We recommend you also learn more about:

* [VTEX authentication for developers](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication).
* [VTEX native login](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/authentication-page--21CkKHLKP1o41lUpGhuRUs)
* [VTEX native login settings](https://read.calvincode.net/reader?url=https://help.vtex.com/en/subcategory/authentications-settings--cgsivNN3J6M6gKAYoeIww)

### Authenticating shopper identity

Currently, VTEX does not support any form of headless shopper authentication. Because of this, we recommend that you direct shoppers to the native VTEX login page so they can log in to your store.

Whenever a shopper requires authentication in your store, your interface must:

1. Direct the shopper to this URL on an internet browser:

`1

{yourStoreUrl}/login

`

1. Once the shopper has successfully logged in, VTEX will set a [user token](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication%23user-token) in a cookie named `VtexIdclientAutCookie`.
2. Store this user token. You must use it to authenticate API requests.

### Authenticating requests to VTEX APIs

There are different [machine authentication methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication%23machine-authentication) available for you to authenticate your integration's requests to VTEX APIs.

For the purpose of headless stores, we recommend using [user tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication%23user-token) whenever possible. You can obtain this token as indicated in the section [Authenticating shoppers' identity](#authenticating-shopper-identity).

You can also use [application keys](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication%23api-keys) in contexts where shoppers authentication is not necessary, such as product search.

## Shopping experience

You can think of a customer's journey in your headless store as divided into three main parts, which connect to different VTEX APIs and features. See the guides below to learn how to implement each of these parts:

* [Viewing catalog information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-catalog)
* [Placing orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-cart-and-checkout)
* [Viewing account information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-profile-management-and-order-history)

Contributors

3

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

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

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/headless-commerce.md)

[Managing VTEX gift cards« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce//docs/guides/managing-vtex-gift-cards)[Headless catalogNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce//docs/guides/headless-catalog)

Contributors

3

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

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

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

ON THIS PAGE

[Authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authentication)

[Authenticating shopper identity](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authenticating-shopper-identity)[Authenticating requests to VTEX APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authenticating-requests-to-vtex-apis)

[Shopping experience](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23shopping-experience)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/headless-commerce.md)

Copy page

On this page

ON THIS PAGE

[Authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authentication)

[Authenticating shopper identity](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authenticating-shopper-identity)[Authenticating requests to VTEX APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23authenticating-requests-to-vtex-apis)

[Shopping experience](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/headless-commerce/docs/guides/headless-commerce%23shopping-experience)

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

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

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

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

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

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

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

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

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

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

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

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

Retrieving ads

Learn how to fetch relevant ads based on context like search terms, categories, or behavior.

The VTEX Ads API allows you to retrieve three types of ad formats:

* Sponsored products (Product ads)
* Sponsored brands
* Banner / Display ads

Use 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-) endpoint to fetch both formats through a unified interface.

> Responses are cached for 10 minutes.

All ad requests require:

* A context (search, category, brand, product, or home)
* User identification (`user_id` and `session_id`)
* Placement configuration

Learn more about each field in the [API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-).

## Request best practices

* **HTTP persistence:** Prefer persistent connections (`Connection: keep-alive`).
* **Timeout:** Apply a 500–600 ms timeout to the ad query.

## Context and ad eligibility rules

> It's not possible to filter by specific `placement`. Ad selection is based on `context` and request parameters.

Understanding which ad types are eligible for each context is crucial for setting up your ad requests correctly.

### Search context

Used when retrieving ads for search results pages.

Eligible ad types:

* **Banner/Video/Sponsored Brands Ads** that are **keyword-based**.
* **Sponsored Products** (any product campaign).

> Keyword matching in the `search` context is exact (no stemming/synonyms). This means the advertiser must specify exactly which keywords they want to use in Banner/Video/Sponsored Brands campaigns. If a user searches for "nike shoes", the ad will only be eligible if the advertiser registered exactly the keyword "nike shoes". There is no approximate matching or similar word matching.

`1

{

2

 "context": "search",

3

 "term": "desodorante",

4

 "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",

5

 "session_id": "f361661f-5986-4779-9009-a34562f18347",

6

 "tags": ["Mega Maio"],

7

 "placements": {

8

 "placementName1": { "quantity": 1, "size": "desktop", "types": ["banner"] },

9

 "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }

10

 }

11

}

`

### Category context

Used for category pages.

Eligible ad types:

* **Banner/Video/Sponsored Brands Ads** that use the corresponding **category**.
* **Sponsored Products** from the category.

`1

{

2

 "context": "category",

3

 "category_name": "Telefones e Celulares > Smartphones > iPhone",

4

 "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",

5

 "session_id": "f361661f-5986-4779-9009-a34562f18347",

6

 "placements": {

7

 "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },

8

 "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }

9

 }

10

}

`

### Brand context

Used for brand-specific pages.

Eligible ad types:

* **Banner/Video/Sponsored Brands Ads** for the brand.
* **Sponsored Products** from the brand.

`1

{

2

 "context": "brand",

3

 "brand_name": "iphone",

4

 "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",

5

 "session_id": "f361661f-5986-4779-9009-a34562f18347",

6

 "placements": {

7

 "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },

8

 "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }

9

 }

10

}

`

### Product context (PDP)

Used on product detail pages.

Eligible ad types:

* **Sponsored Products** related to the viewed product.

`1

{

2

 "context": "product_page",

3

 "product_sku": "120210",

4

 "product_attributes": {

5

 "category_name": "Telefones e Celulares > Smartphones > iPhone",

6

 "brand": "iphone"

7

 },

8

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

9

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

10

 "placements": {

11

 "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },

12

 "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }

13

 }

14

}

`

### Home context

Used for homepage or non-targeted contexts. Shows ads most relevant to the user based on their history.

Eligible ad types:

* **Banner/Video/Sponsored Brands Ads** that use **category** as a targeting criterion.
* **Sponsored Products**.

`1

{

2

 "context": "home",

3

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

4

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

5

 "placements": {

6

 "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },

7

 "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }

8

 }

9

}

`

## Response structure

> Successful responses return HTTP code 200.

The response is a dictionary where:

* Each key corresponds to a placement name from the request.
* Results maintain the same order as the query.
* Each ad includes tracking URLs for clicks, impressions and views.

### Standard ad response example

`1

{

2

 "placementName1": [

3

 {

4

 "ad_id": "6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce",

5

 "media_url": "https://cdn.newtail.com.br/retail_media/ads/2023/05/03/f97a938660e56fe38a9c9ade21c27df8-1280x256-red.png",

6

 "destination_url": null,

7

 "type": "banner",

8

 "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner",

9

 "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner",

10

 "view_url": "https://events.newtail-media.newtail.com.br/v1/beacon/view/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner"

11

 }

12

 ]

13

}

`

### Sponsored brands example

Sponsored brands campaigns have a different response format that includes brand information and related products.

> 🚧 All events must be triggered for both the ad and its products.

Request example:

`1

{

2

 "context": "search",

3

 "term": "smartphone",

4

 "placements": {

5

 "placement_name": { "quantity": 1, "types": ["sponsored_brand"] }

6

 }

7

}

`

Response example:

`1

{

2

 "placement_name": [

3

 {

4

 "type": "sponsored_brand",

5

 "assets": [

6

 {

7

 "type": "image|video",

8

 "url": "Image URL"

9

 }

10

 ],

11

 "brand_url": "https://cdn.newtail.com.br/retail_media/brands/logo.jpeg",

12

 "brand_name": "Apple",

13

 "destination_url": "https://www.extra.com.br/c?Filter=D70653",

14

 "headline": "Titanium. Very robust, very light, very pro!",

15

 "description": "",

16

 "view_url": "VIEW URL",

17

 "impression_url": "IMPRESSION URL",

18

 "click_url": "CLICK URL",

19

 "products": [

20

 {

21

 "image_url": "PRODUCT IMAGE URL",

22

 "seller_id": null,

23

 "product_metadata": { },

24

 "product_name": "iPhone 15 Pro MAX",

25

 "product_sku": "55064355",

26

 "destination_url": "PRODUCT URL",

27

 "impression_url": "IMPRESSION URL for a specific PRODUCT",

28

 "view_url": "VIEW URL for a specific PRODUCT",

29

 "click_url": "CLICK URL for a specific PRODUCT"

30

 }

31

 ]

32

 }

33

 ]

34

}

`

## Best practices

### Placement naming

Adopt a clear standard, such as `{channel}_{context}_{position}_{type}` (e.g., `msite_search_top-shelf_product`).

Examples:

* `site_home_middle_banner`
* `msite_product_top-shelf_product`
* `app_search_top-shelf_product`
* `site_category_bottom-shelf_banner`

### IAB standard image sizes

For banner-type ads, use images in the standard formats defined by the IAB (Interactive Advertising Bureau) to ensure compatibility and a better visual experience:

* **Medium Rectangle:** 300x250 pixels
* **Leaderboard:** 728x90 pixels
* **Wide Skyscraper:** 160x600 pixels
* **Mobile Leaderboard:** 320x50 pixels
* **Billboard:** 970x250 pixels
* **Half Page:** 300x600 pixels

### Video size options

For video ad requests, specify the size parameter to filter by video resolution:

* **1080p** (1920x1080 pixels) - Recommended only for full-screen videos
* **720p** (1280x720 pixels) - Recommended only for full-screen videos
* **480p** (854x480 pixels)
* **360p** (640x360 pixels)
* **320p** (568x320 pixels) - Recommended for mobile devices

> Use only the resolution identifier (e.g., `"720p"`) in the size parameter, not the full dimensions.

## Ad targeting

Target ads to specific audiences to increase relevance by sending demographic or audience data directly in the body of the ad query using the `segmentation` field.

The `segmentation` field is an array of objects, where each object contains:

* `key`: The type of segmentation (e.g., "STATE", "CITY", "GENDER").
* `values`: Array of values for the segmentation.

### Segmentation example

`1

{

2

 "context": "search",

3

 "term": "smartphone",

4

 "segmentation": [

5

 {

6

 "key": "STATE",

7

 "values": ["CA"]

8

 },

9

 {

10

 "key": "CITY",

11

 "values": ["San Francisco"]

12

 },

13

 {

14

 "key": "GENDER",

15

 "values": ["M"]

16

 }

17

 ],

18

 "placements": {

19

 "site_search_top_product": {

20

 "quantity": 5,

21

 "types": ["product"]

22

 }

23

 }

24

}

`

**Available segmentation types:**

* `STATE` \- User's state (e.g., "CA", "NY", "TX").
* `CITY` \- User's city (e.g., "San Francisco", "New York").
* `GENDER` \- User's gender (e.g., "M", "F").
* `AGE` \- User's age (e.g., "22", "35").
* `AUDIENCES` \- Custom audience (e.g., "high\_value\_customers", "cart\_abandoners").
* `NBO_CATEGORIES` \- Possible categories the user intends to buy (e.g., "Electronics", "Books").

## Response codes and errors

* **200 OK:** Query processed successfully (returns JSON per placement).
* **422 Unprocessable Entity:** Field validation error.
* **400 Bad Request / 404 Not Found:** Invalid request or resource not found.
* **429 Too Many Requests:** Rate limit exceeded.
* **5xx:** Internal errors.

Contributors

1

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

[Synchronizing inventory information« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads//docs/guides/synchronizing-inventory-information)[Segmenting campaignsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads//docs/guides/segmenting-campaigns)

Contributors

1

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

[Request best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23request-best-practices)

[Context and ad eligibility rules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23context-and-ad-eligibility-rules)

[Search context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23search-context)[Category context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23category-context)[Brand context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23brand-context)[Product context (PDP)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23product-context-pdp)[Home context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23home-context)

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

[Standard ad response example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23standard-ad-response-example)[Sponsored brands example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23sponsored-brands-example)

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

[Placement naming](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23placement-naming)[IAB standard image sizes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23iab-standard-image-sizes)[Video size options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23video-size-options)

[Ad targeting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23ad-targeting)

[Segmentation example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23segmentation-example)

[Response codes and errors](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23response-codes-and-errors)

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

Copy page

On this page

ON THIS PAGE

[Request best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23request-best-practices)

[Context and ad eligibility rules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23context-and-ad-eligibility-rules)

[Search context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23search-context)[Category context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23category-context)[Brand context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23brand-context)[Product context (PDP)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23product-context-pdp)[Home context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23home-context)

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

[Standard ad response example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23standard-ad-response-example)[Sponsored brands example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23sponsored-brands-example)

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

[Placement naming](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23placement-naming)[IAB standard image sizes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23iab-standard-image-sizes)[Video size options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23video-size-options)

[Ad targeting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23ad-targeting)

[Segmentation example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23segmentation-example)

[Response codes and errors](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/retrieving-ads/docs/guides/retrieving-ads%23response-codes-and-errors)

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 using advanced layouts 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-using-advanced-layouts/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/updates/release-notes)

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/faststore)

---

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

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

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-building-pages)

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

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

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

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

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

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

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

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-routing)

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

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

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

---

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

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

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

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

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

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

---

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

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/faststore)

---

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

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

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-building-pages)

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

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

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

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

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

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

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

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/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-using-advanced-layouts/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-routing)

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

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

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

---

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

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

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

Using advanced layouts

Discover how to create advanced layouts in your Store Framework store.

In this section, you'll learn how to use advanced layout components in your Store Framework store to improve your storefront design and functionality.

Advanced layout components, as well as other components, are built on the [VTEX IO development platform](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io) using [React](https://read.calvincode.net/reader?url=https://react.dev/) technology. To learn more about the use of components, see the section [Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-components).

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

* [Condition Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.condition-layout): Renders a component in your store when predefined conditions are met.
* [Disclosure Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.disclosure-layout): Creates a layout structure based on disclosure indicators.
* [Flex Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.flex-layout): Allows building complex custom layouts using the concept of rows and columns.
* [Modal Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.modal-layout): Provides blocks to help you create modals in your store.
* [Overlay Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.overlay-layout): Provides blocks to create a Dropdown, Select, or Tooltip component.
* [Responsive Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.responsive-layout): Allows you to declare layout structures that will only be rendered in a specific screen-size breakpoint.
* [Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.slider-layout): Allows building block sliders, such as carousels.
* [Stack Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.stack-layout): Shows blocks on top of other blocks.
* [Sticky Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.sticky-layout): Provides layout structures to build elements that remain fixed relative to the viewport in certain contexts.
* [Tab Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.tab-layout): Creates different layouts within the store's main one using _tabs_.

## Before you begin

### Have a Store Framework store

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 [Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-3) tutorial.

### Check the builders

Check if the builders are properly installed in your Store Theme. To use builders, your account must have at least version `vtex.builder-hub@0.293.4` installed. Also, you need to specify them in the app's manifest.json file. Learn more in [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 when your project requires customized frontend solutions.

### Learn about VTEX IO apps

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

## Guides in this section

[Building a carousel using Slider LayoutLearn how to integrate and customize carousels for your storefront using Slider Layout.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-building-a-carousel-using-slider-layout)[Creating modals using iconsExplore how to create modals using icons to enhance user experience.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-modals-using-icons)[Configuring a quickview using Modal LayoutLearn how to create a quickview feature using the Modal Layout app.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-flex-layout)[Rendering a badge on top of a productDiscover how to render badges on top of products to highlight special offers, discounts, or new arrivals.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-rendering-a-badge)[Using Flex LayoutUnderstand the Flex Layout component to create responsive layouts for your store.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-flex-layout)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/_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-using-advanced-layouts.md)

[Setting up Delivery Promise components (Beta)« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts//docs/guides/setting-up-delivery-promise-components)[Building a Carousel using Slider LayoutNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts//docs/guides/vtex-io-documentation-building-a-carousel-using-slider-layout)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/_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-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23before-you-begin)

[Have a Store Framework store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23have-a-store-framework-store)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23check-the-builders)[Learn about VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23learn-about-vtex-io-apps)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%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-using-advanced-layouts.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-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23before-you-begin)

[Have a Store Framework store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23have-a-store-framework-store)[Check the builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23check-the-builders)[Learn about VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%23learn-about-vtex-io-apps)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-framework-using-advanced-layouts/docs/guides/store-framework-using-advanced-layouts%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=)