[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 creating a custom search results page 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-creating-a-custom-search-results-page/docs/guides)

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/faststore)

---

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

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

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

Concepts

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

[Building a Product Details Page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-building-a-product-details-page)

[Building a search results page with multiple layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-building-a-search-results-page-with-multiple-layouts)

[Creating a Black Friday page from template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-black-friday-page-from-template)

[Creating a custom search results page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page)

[Creating a new custom page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-new-custom-page)

[Customizing the Header and Footer blocks by page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-customizing-the-header-and-footer-blocks-by-page)

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

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

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

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

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

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

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides)

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/troubleshooting)

---

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/faststore)

---

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

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

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

Concepts

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

[Building a Product Details Page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-building-a-product-details-page)

[Building a search results page with multiple layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-building-a-search-results-page-with-multiple-layouts)

[Creating a Black Friday page from template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-black-friday-page-from-template)

[Creating a custom search results page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page)

[Creating a new custom page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-new-custom-page)

[Customizing the Header and Footer blocks by page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-customizing-the-header-and-footer-blocks-by-page)

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

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

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

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

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

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

---

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

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

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

[Creating a custom search results page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page)

Creating a custom search results page

When [creating a new landing page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-new-custom-page/) for your store's website, you can configure it as a custom search results page to promote specific products.

Although custom pages do not inherently fetch search data, the `search-result-layout.customQuery` block from the [Search Result app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-result/) allows you to specify the query to render the desired search results for your users.

## Before you begin

To build a custom search results page, familiarize yourself with the [Search Result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-result) app to understand the blocks exported by this app, including the `search-result-layout.customQuery`.

## Instructions

1. Open your Store Theme app directory using your preferred code editor.
2. In the `routes.json` file, define a new path called `store.custom#landing`. Replace the `path` value as needed for your scenario.
`1
"store.custom#landing": {
2
 "path": "/landing"
3
}
`
3. In the `blocks.jsonc` folder, create a new file (e.g., `search-landing.jsonc`) to store the new custom search results page blocks.
4. In the new file, declare the template name, such as `store.custom#landing`. Ensure the name matches the one declared in step 2.
5. In the template's block list, add any theme block you want to build your new custom page. The `search-result-layout.customQuery` block is mandatory to define how the search query should be fetched. For example:
search-landing.jsonc
`1
{
2
 "store.custom#landing": {
3
 "blocks": [
4
 "image#landingbanner",
5
 "search-result-layout.customQuery"
6
 ]
7
 }
8
}
`
6. Declare the blocks according to the search results custom page you wish to have. Below you can find an example of a custom search results template:
search-landing.jsonc
`1
{
2
 "store.custom#landing": {
3
 "blocks": ["image#landing", "search-result-layout.customQuery"]
4
 },
5
 "image#landing": {
6
 "props": {
7
 "minWidth": "100%",
8
 "src": "https://user-images.githubusercontent.com/18701182/69889938-64b16180-12d2-11ea-8d8a-e3089cbeaffd.png"
9
 }
10
 },
11
 "search-result-layout.customQuery": {
12
 "props": {
13
 "querySchema": {
14
 "orderByField": "OrderByReleaseDateDESC",
15
 "hideUnavailableItems": true,
16
 "maxItemsPerPage": 8,
17
 "queryField": "Blue Top Retro Camera",
18
 "mapField": "ft"
19
 }
20
 },
21
 "blocks": [
22
 "search-result-layout.desktop",
23
 "search-result-layout.mobile",
24
 "search-not-found-layout"
25
 ]
26
 },
27
 "search-result-layout.desktop": {
28
 "children": [
29
 "breadcrumb.search",
30
 "search-title.v2",
31
 "flex-layout.row#top",
32
 "search-fetch-previous",
33
 "flex-layout.row#results",
34
 "search-fetch-more"
35
 ],
36
 "props": {
37
 "pagination": "show-more",
38
 "preventRouteChange": true
39
 }
40
 },
41
 "flex-layout.row#top": {
42
 "children": [
43
 "total-products.v2",
44
 "order-by.v2"
45
 ]
46
 },
47
 "flex-layout.row#results": {
48
 "children": [
49
 "flex-layout.col#filter",
50
 "flex-layout.col#search"
51
 ]
52
 },
53
 "flex-layout.col#filter": {
54
 "props": {
55
 "width": "20%"
56
 },
57
 "children": [
58
 "filter-navigator.v3"
59
 ]
60
 },
61
 "flex-layout.col#search": {
62
 "children": [
63
 "search-content"
64
 ]
65
 },
66
 "search-content": {
67
 "blocks": ["gallery", "not-found"]
68
 },
69
 "gallery": {
70
 "blocks": ["product-summary.shelf"]
71
 }
72
}
`
7. Save the changes made in your Store Theme app.
8. Open the terminal, log in to your VTEX Account and [create a new development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace/).
9. Once logged into the desired account and workspace, [link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app/) your Store Theme app to see your new custom page live.
10. Access your store's website using the following format: `{workspaceName}--{accountName}.myvtex.com/{pathName}` to see your new page live.

Once you are satisfied with the changes to your Store Theme, [make your new theme content publicly available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-making-your-theme-content-public/).

Contributors

1

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Storefront-Guides/concepts-1/vtex-io-documentation-creating-a-custom-search-results-page.md)

[Creating a Black Friday page from template« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page//docs/guides/vtex-io-documentation-creating-a-black-friday-page-from-template)[Creating a new custom pageNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page//docs/guides/vtex-io-documentation-creating-a-new-custom-page)

Contributors

1

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

ON THIS PAGE

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

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

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Storefront-Guides/concepts-1/vtex-io-documentation-creating-a-custom-search-results-page.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-creating-a-custom-search-results-page/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page%23before-you-begin)

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

On this page

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


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

[User] Provide a guide on guides storefront permissions 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/storefront-permissions/docs/guides)

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

Storefront Permissions

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

Storefront Permissions

Learn how to manage user access and roles within the storefront using the Storefront Permissions API for B2B scenarios.

> This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://read.calvincode.net/reader?url=https://support.vtex.com/hc/en-us/).

The [Storefront Permissions API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23overview) provides a structured way to manage user access and roles within the storefront. It enables organizations to define and enforce authorization policies by controlling which actions users can perform.

The Storefront Permissions API allows you to:

* Assign and revoke roles for storefront users.
* Validate access by checking whether a user has permission to perform a specific action.
* Retrieve details about user roles and permissions.
* Manage access to resources such as orders, addresses, authentication settings, and payment methods.

## Key concepts

* **Storefront resources**: Fine-grained permissions that define a specific capability in the storefront (for example, `PlaceOrders`, `ApproveOrders`, `ManageAddresses`).
* **Storefront roles**: Logical groupings of resources that represent common permission sets (for example, `Buyer`, `Order Approver`, `Organizational Unit Admin`).
* **Storefront users**: Storefront identities (customers or organization members) to whom roles and resources are assigned.

## Use cases

This functionality is particularly relevant in B2B contexts, where multiple users within the same organization may require different access levels based on their role in the purchasing process.

The Storefront Permissions API supports a wide range of business scenarios by enabling control over user access, such as:

* Granting buyers permission to place orders while restricting order approvals to designated approvers.
* Allowing managers to oversee all orders within their organizational unit.
* Enabling administrators to configure organizational structures, contracts, and user access.

## Before you begin

* All endpoints require the Storefront Permissions feature to be enabled on your account. Requests sent to accounts without this feature enabled return a “Feature not enabled for this account” error.
* Any user or [API key](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/authentication-overview%23api-keys) must have the appropriate [License Manager resources](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run requests to the License Manager API as listed in the table below. Otherwise, they will receive a status code 403 error.

| Product         | Category                | Resource                         | Associated endpoints                                                                                |
| --------------- | ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| License Manager | Services access control | View Storefront User Permissions | GET [Check storefront user resource access](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23get-/api/license-manager/storefront/users/-userId-/resources/-resourceKey-/granted) GET [Fetch storefront user roles by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23get-/api/license-manager/storefront/users/-userId-/roles) GET [Fetch storefront user roles by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23get-/api/license-manager/storefront/users/-email-/roles) GET [Fetch storefront user details](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23get-/api/license-manager/storefront/users/-userId-) |
| License Manager | Services access control | Edit Storefront User Permissions | POST [Create storefront user](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23post-/api/license-manager/storefront/users/) POST [Assign storefront role to user](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23post-/api/license-manager/storefront/roles/assign) DELETE [Revoke storefront role from user](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23delete-/api/license-manager/storefront/roles/revoke) DELETE [Remove storefront user](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/storefront-permissions-api%23delete-/api/license-manager/storefront/remove/users/-userId-)                                                              |

To learn more about machine authentication at VTEX, see [Authentication overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/authentication-overview%23machine-authentication).

## Available storefront resources

The following resource keys are available in the system:

| Resource Key                  | Description                                                                                |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| ManageOrganizationAndContract | Allows management of the organization's structure, contracts, and related settings.             |
| PlaceOrders                   | Grants the ability to create and submit orders within the system.                               |
| ViewMyContractOrders          | Enables users to see orders placed under their assigned contract.                               |
| ViewMyOrgUnitOrders           | Allows users to view all orders within their organizational unit.                               |
| ModifyOrders                  | Provides permission to use the change order feature for all orders that the user has access to. |
| ApproveOrders                 | Grants the ability to approve or reject orders based on predefined workflows.                   |
| ManageAddresses               | Add the address during checkout and save it for that contract/organization unit.                |
| UseAdHocCard                  | Grants permission to use a new credit card at checkout.                                         |
| SavePrivateCard               | Grants permission to save a new card for the user's use only.                                   |
| ViewProfile                   | Allows access to view the profile information.                                                  |
| ManageAuthentication          | Provides access to authentication settings.                                                     |
| ViewMyCards                   | Enables users to view their payment cards.                                                      |
| ViewAddresses                 | Allows users to manage and update their saved addresses.                                        |

## Predefined storefront roles

The system comes with these predefined storefront roles, each with specific permissions:

| Predefined storefront role | Storefront role ID | Description                                                                 | Associated resources                    |
| -------------------------- | ------------------ | --------------------------------------------------------------------------- | --------------------------------------- |
| Organizational Unit Admin  | 1                  | Manages the organization's structure, contracts, and related settings.      | ManageOrganizationAndContract           |
| Order Approver             | 2                  | Can approve or reject orders based on predefined workflows.                 | ApproveOrders                           |
| Order Modifier             | 3                  | Can use the change order feature for all orders they have access to.        | ModifyOrders                            |
| Buyer                      | 4                  | Can create and submit orders within the system.                             | PlaceOrders                             |
| Personal Cards User        | 5                  | Can use a new credit card at checkout and save cards for personal use only. | UseAdHocCard, SavePrivateCard           |
| Contract Manager           | 6                  | Can view orders placed under their assigned contract.                       | ViewMyContractOrders                    |
| Buyer Organization Manager | 7                  | Can view all orders within their organizational unit.                       | ViewMyOrgUnitOrders                     |
| Contract Viewer            | 8                  | Can view profiles, payment cards, and addresses.                            | ViewProfile, ViewMyCards, ViewAddresses |
| Address Manager            | 9                  | Can add and manage addresses during checkout.                               | ManageAddresses                         |

Contributors

1

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

[Delivery promise for headless stores (Beta)« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions//docs/guides/delivery-promise-for-headless-stores)[VTEX Activity FlowNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions//docs/guides/activity-flow)

Contributors

1

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

[Key concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23key-concepts)

[Use cases](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23use-cases)

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

[Available storefront resources](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23available-storefront-resources)

[Predefined storefront roles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23predefined-storefront-roles)

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/Storefront-Permissions/storefront-permissions.md)

Copy page

On this page

ON THIS PAGE

[Key concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23key-concepts)

[Use cases](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23use-cases)

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

[Available storefront resources](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23available-storefront-resources)

[Predefined storefront roles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/storefront-permissions/docs/guides/storefront-permissions%23predefined-storefront-roles)

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

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

[Categories](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/categories)

[Brands](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/brands)

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

[Specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/specifications)

[Product specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/product-specifications)

[SKU specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/sku-specifications)

[Updating SKU Specifications with Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/updating-sku-specifications-with-catalog-api)

[SKUs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/skus)

[Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/images)

[Alternative API requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/alternative-api-requests)

[How to implement product color variation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/how-to-implement-product-color-variation)

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

[Categories](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/categories)

[Brands](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/brands)

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

[Specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/specifications)

[Product specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/product-specifications)

[SKU specifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/sku-specifications)

[Updating SKU Specifications with Catalog API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/updating-sku-specifications-with-catalog-api)

[SKUs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/skus)

[Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/images)

[Alternative API requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/alternative-api-requests)

[How to implement product color variation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/how-to-implement-product-color-variation)

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

Products

A product is a generic definition of an item that is part of your store’s Catalog, for instance, a shirt.

Products may vary by model, color, size, among other characteristics. Therefore, it would be possible to have the same product (shirt) in different models, like short or long sleeves, gray or pink color, sizes S, M or L.

Each variation, such as a _long sleeve gray size S shirt_, will correspond to a [Stock Keeping Unit (SKU)](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/3mJbIqMlz6oKDmyZ2bKJoA), which is the actual item in the inventory that customers can purchase. Before creating SKUs, you must create a product.

> Try the interactive version of this article by accessing this [link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-products). Code will be highlighted and focused for your convenience.

## Create a product

To insert a new product, use the [Create product API endpoint](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api%23post-/api/catalog/pvt/product).

When creating or updating products, note that any product must be associated with their corresponding [category](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/categories) in the more specific category level.

> We recommend leaving VTEX to automatically generate an ID, by not including a custom product ID in the Id field of the request body. The generated ID can be retrieved in the request's response and must be stored in the system for future updates of this product.

#### **Request body example**

`1

{

2

 "Id": null,

3

 "Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

4

 "DepartmentId": 2000089,

5

 "CategoryId": 2000090,

6

 "BrandId": 12121219,

7

 "LinkId": "stefan-janoski-canvas-varsity-red",

8

 "RefId": "sr_1_90",

9

 "IsVisible": true,

10

 "Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

11

 "DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",

12

 "ReleaseDate": "2023-01-01T00:00:00",

13

 "KeyWords": "Zoom,Stefan,Janoski",

14

 "Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

15

 "IsActive": true,

16

 "MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

17

 "ShowWithoutStock": true,

18

}

`

#### **Response body example**

`1

{

2

 "Id": 42,

3

 "Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

4

 "DepartmentId": 2000089,

5

 "CategoryId": 2000090,

6

 "BrandId": 12121219,

7

 "LinkId": "stefan-janoski-canvas-varsity-red",

8

 "RefId": "sr_1_90",

9

 "IsVisible": true,

10

 "Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

11

 "DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",

12

 "ReleaseDate": "2023-01-01T00:00:00",

13

 "KeyWords": "Zoom,Stefan,Janoski",

14

 "Title": "Zoom Stefan Janoski Canvas RM SB Varsity Re",

15

 "IsActive": true,

16

 "TaxCode": "",

17

 "MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

18

 "SupplierId": 1,

19

 "ShowWithoutStock": true,

20

 "AdWordsRemarketingCode": null,

21

 "LomadeeCampaignCode": null,

22

 "Score": 1

23

}

`

## Update a product

In case you have already created a product and want to change it, use the [Update product API request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api%23put-/api/catalog/pvt/product/-productId-), sending in the `Id` of the product already created.

> If you need to change any product field, it is necessary to send all the other fields in the request. Otherwise, all previously configured information from blank fields will be deleted. Therefore, before making a change, you should get the product data for the same `Id` and use the response as a template to make the change.

#### **Request body example**

`1

{

2

 "Id": 42,

3

 "Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

4

 "DepartmentId": 2000089,

5

 "CategoryId": 2000090,

6

 "BrandId": 12121219,

7

 "LinkId": "stefan-janoski-canvas-varsity-red",

8

 "RefId": "sr_1_90",

9

 "IsVisible": true,

10

 "Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

11

 "DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",

12

 "ReleaseDate": "2023-01-01T00:00:00",

13

 "KeyWords": "Zoom,Stefan,Janoski",

14

 "Title": "Zoom Stefan Janoski Canvas RM SB Varsity Re",

15

 "IsActive": true,

16

 "TaxCode": "",

17

 "MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

18

 "SupplierId": 1,

19

 "ShowWithoutStock": true,

20

 "AdWordsRemarketingCode": null,

21

 "LomadeeCampaignCode": null,

22

 "Score": 1

23

}

`

#### **Response body example**

`1

{

2

 "Id": 42,

3

 "Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

4

 "DepartmentId": 2000089,

5

 "CategoryId": 2000090,

6

 "BrandId": 12121219,

7

 "LinkId": "stefan-janoski-canvas-varsity-red",

8

 "RefId": "sr_1_90",

9

 "IsVisible": true,

10

 "Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

11

 "DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",

12

 "ReleaseDate": "2023-01-01T00:00:00",

13

 "KeyWords": "Zoom,Stefan,Janoski",

14

 "Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",

15

 "IsActive": true,

16

 "TaxCode": "",

17

 "MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",

18

 "SupplierId": 1,

19

 "ShowWithoutStock": true,

20

 "AdWordsRemarketingCode": null,

21

 "LomadeeCampaignCode": null,

22

 "Score": 1

23

}

`

Contributors

2

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

[Brands« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products//docs/guides/brands)[SpecificationsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products//docs/guides/specifications)

Contributors

2

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

ON THIS PAGE

[Create a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/products%23create-a-product)

[Update a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/products%23update-a-product)

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/catalog-integration/products.md)

Copy page

On this page

ON THIS PAGE

[Create a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/products%23create-a-product)

[Update a product](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/products/docs/guides/products%23update-a-product)

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] How do I use the VTEX store link app? Provide documentation and configuration details.

[Assistant]
Documentation

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

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

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

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

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

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

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

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

VTEX IO Apps

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

---

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

---

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

[Availability Notify](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.availability-notify)

[Category Menu](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.category-menu)

[Kit Look](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexbr.kitlook)

[Icon Pack list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-icons/iconpack)

[Iframe](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.iframe)

[Live Shopping](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexventures.livestreaming)

[PayPal Checkout with Smart Payment Buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.connector-paypal-commerce-platform)

[Personal Shopper](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexventures.personal-shopper-free)

[Product Availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-availability)

[Product Comparison](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-comparison)

[Product Gifts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-gifts)

[Product Highlight by VTEX Segment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexarg.product-highlight-by-vtex-segment)

[Product Specification Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-specification-badges)

[Quantity On Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexarg.quantity-on-cart)

[Reviews and Ratings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.reviews-and-ratings)

[Querying personal MasterData Information with SafeData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.safedata)

[Seller Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.seller-selector)

[Similar Products Variants](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.similar-products-variants)

[Store Drawer](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-drawer)

[Store Locator](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-locator)

[Store Form](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-form)

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

[Store Media](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-media)

[Store Newsletter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-newsletter)

[Video](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-video)

[VTEX IO Sandbox Component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.sandbox)

[Shipping Option Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.shipping-option-components)

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

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

---

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

---

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

[Availability Notify](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.availability-notify)

[Category Menu](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.category-menu)

[Kit Look](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexbr.kitlook)

[Icon Pack list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-icons/iconpack)

[Iframe](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.iframe)

[Live Shopping](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexventures.livestreaming)

[PayPal Checkout with Smart Payment Buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.connector-paypal-commerce-platform)

[Personal Shopper](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexventures.personal-shopper-free)

[Product Availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-availability)

[Product Comparison](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-comparison)

[Product Gifts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-gifts)

[Product Highlight by VTEX Segment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexarg.product-highlight-by-vtex-segment)

[Product Specification Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.product-specification-badges)

[Quantity On Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtexarg.quantity-on-cart)

[Reviews and Ratings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.reviews-and-ratings)

[Querying personal MasterData Information with SafeData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.safedata)

[Seller Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.seller-selector)

[Similar Products Variants](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.similar-products-variants)

[Store Drawer](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-drawer)

[Store Locator](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-locator)

[Store Form](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-form)

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

[Store Media](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-media)

[Store Newsletter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-newsletter)

[Video](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-video)

[VTEX IO Sandbox Component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.sandbox)

[Shipping Option Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.shipping-option-components)

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

Store Link

Official extension

Version: 0.9.4

Latest version: 0.9.4

[![{"base64":"  ","img":{"width":110,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)

The Store Link app provides blocks for displaying links in other theme blocks, such as Product Summary.

![{"base64":"  ","img":{"width":1490,"height":834,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":705454,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-link-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-link-0.png)

## Configurating the store link

1. Add the `store-link` app to your theme dependencies in the `manifest.json` file. Then, you can use all the [blocks](#blocks) exported by the `store-link` app and its respective [props](#props).

`1

 "dependencies": {

2

+ "vtex.store-link": "0.x"

3

 }

`

1. Choose one of the [blocks](#blocks) exported by the `store-link` app and declare it in the block where the link will be displayed. See below an example of a `link.product` being used in the [product-summary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary) block to display the "More details" link.

`1

{

2

 "link.product#product-page": {

3

 "props": {

4

 "href": "/{slug}/p",

5

 "label": "More details >"

6

 }

7

 },

8

 "product-summary.shelf": {

9

 "children": [

10

 "product-summary-image",

11

 "product-summary-name",

12

 "product-rating-inline",

13

 "product-summary-space",

14

 "product-summary-price",

15

 "link.product#product-page"

16

 ]

17

 },

18

}

`

> Note that you must place the `link.product` block inside a block that provides a product context (e.g., [ProductSummary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary)). From the previous example, note that a `{slug}` placeholder is being passed onto the `href` prop. When rendered, this placeholder is overwritten by the value accrued from the closest product context, generating a link like `/everyday-necessaire/p`.

## Blocks

| Block        | Description                                                                                |
| ------------ | --------------------------------------------------------------------------------------------------- |
| link.product | A link that uses the product context, such as a product slug or department. For example, /{slug}/p. |
| link         | A regular link that does not require the product context to function. For example, /home.           |

## Props

All blocks exported by `store-link` share the same props:

| Prop name       | Type   | Description                                                                                | Default value                       |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| label           | string | Link text.                                                                                | undefined                           |
| href            | string | Link URL.                                                                                | #                                   |
| scrollTo        | string | Element anchor to scroll after navigation. (E.g. "#footer")                                                                                | undefined                           |
| target          | string | Where the linked URL will be displayed. This prop works the same way as the target from [HTML <a> element](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a). Since the [_anchor_ element's target](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a%23attr-target) default is \_self, this prop will be set to \_self if it is undefined. | undefined                           |
| displayMode     | enum   | How the link will be displayed. Possible values are: anchor (displays a normal link with no styles) or button (displays a button that can be customized using the buttonProps prop).                                                                                | anchor                              |
| buttonProps     | object | How the link button will be displayed. Use this prop only when the displayMode prop is set as button.                                                                                | { variant: primary, size: regular } |
| escapeLinkRegex | string | RegExp, with global match, used to remove special characters within product specifications (e.g., if you want to use /\[%\]/g then escapeLinkRegex \= \[%\]).                                                                                | undefined                           |
| rel             | string | This prop specifies the relationship between the current document and linked ones for better SEO. This prop works the same way as the rel attribute from <a>, the [HTML anchor element](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a). You can see supported values [here](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/HTML/Link%5Ftypes).     | undefined                           |

* `buttonProps` object:

| Prop name | Type | Description                                                                                | Default value |
| --------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| variant   | enum | Link button that has visual prominence. Possible values are: primary or secondary (values are set following the [VTEX Styleguide](https://read.calvincode.net/reader?url=https://styleguide.vtex.com/%23/Components/Forms/Button)). | primary       |
| size      | enum | Link button size. Possible values are: small, regular or large (values are set following the [VTEX Styleguide](https://read.calvincode.net/reader?url=https://styleguide.vtex.com/%23/Components/Forms/Button)).                    | regular       |

## App Behavior

When creating an URL link using the `href` prop, you can add custom query string values, as shown in the example below:

`1

{

2

 "link#foo": {

3

 "props": {

4

 "href": "/login?returnUrl={queryString.returnUrl}",

5

 "label": "Sign in"

6

 }

7

 }

8

}

`

Considering the `href` prop from the previous example, note that the URL link will be built correctly if the current page has the `returnUrl` query string. Otherwise, it will be built with an empty value.

Depending on the context that the `link.product` block uses, you can use product variables to structure different URL paths for the `href` prop. For example, you could create a link to a specific product department (`/{department}`).

| Product variable | Description                                    |
| ---------------- | ---------------------------------------------- |
| brand            | Product brand name.                            |
| brandId          | Product brand ID.                              |
| category1        | Highest level category in the category tree.   |
| category2        | Second highest level category.                 |
| category3        | Third highest level category.                  |
| category4        | Fourth highest level category.                 |
| department       | Product department.                            |
| productId        | Product ID.                                    |
| skuId            | Currently selected SKU ID.                     |
| slug             | The link text used to create the product link. |

To build URLs with variables related to product specifications, use the following format: `{specificationGroups.groupName.specifications.specificationName}`. Replace `groupName` and `specificationName` with the specification group and the product specification names accordingly. For example:

`1

{

2

 "link.product#vtex": {

3

 "props": {

4

 "href": "{specificationGroups.Design.specifications.Dimensions}",

5

 "label": "VTEX"

6

 }

7

 }

8

}

`

In the example above, `Design` is the specification group name, and `Dimensions` is the product specification name.

## Customization

To apply CSS customizations in this and other blocks, see the [Using CSS handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization) guide. All blocks have the same handles.

| CSS handles       |
| ----------------- |
| childrenContainer |
| label             |
| link              |

[Store Form« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-form)[Store MediaNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-media)

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Configurating the store link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-link%23configurating-the-store-link)

[Blocks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-link%23blocks)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-link%23props)

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

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-link/docs/apps/vtex.store-link%23customization)

Was this helpful?

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