[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 external marketplace integration new 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/external-marketplace-integration-new-products/docs/guides)

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

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

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

Guides

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

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/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/external-marketplace-integration-new-products/docs/guides/erp-integration-guide)

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

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

[Marketplace / Seller architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-architecture)

[Store setup for VTEX Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-vtex-seller-setup)

[Creating an integration app from a Template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-app-template)

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

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

[Get product list for an initial load](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-product-load)

[How to get a new product to offer in the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products)

[How to get product updates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-product-updates)

[Product and Category Mappings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-catalog-mapping)

[How to keep prices updated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-price-update)

[How to keep stock updated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-stock-update)

[Order Integration overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-orders)

[Recommendations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-recommendations)

[New Order Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-collect-orders)

[Update Order Status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-update-order-status)

[How to validate if items are available for delivery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-delivery-validation)

[Sending invoice and tracking code to the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-invoice-tracking)

[How to update a canceled order’s status in VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-canceled-orders)

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

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

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

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

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/punchout)

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

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

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

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/session-manager)

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

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/recaptcha)

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/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/external-marketplace-integration-new-products/docs/guides/erp-integration-guide)

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

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

[Marketplace / Seller architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-architecture)

[Store setup for VTEX Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-vtex-seller-setup)

[Creating an integration app from a Template](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-app-template)

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

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

[Get product list for an initial load](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-product-load)

[How to get a new product to offer in the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products)

[How to get product updates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-product-updates)

[Product and Category Mappings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-catalog-mapping)

[How to keep prices updated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-price-update)

[How to keep stock updated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-stock-update)

[Order Integration overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-orders)

[Recommendations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-recommendations)

[New Order Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-collect-orders)

[Update Order Status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-update-order-status)

[How to validate if items are available for delivery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-delivery-validation)

[Sending invoice and tracking code to the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-invoice-tracking)

[How to update a canceled order’s status in VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-canceled-orders)

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

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

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

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

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/punchout)

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

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

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

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/session-manager)

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

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/recaptcha)

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

Integration Guides

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

[How to get a new product to offer in the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products)

How to get a new product to offer in the marketplace

This part of the guide explains how the connector should act when receiving the VTEX notification of a new product or SKU registered. The information flows according to the diagram below:

![{"base64":"  ","img":{"width":5262,"height":1325,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":178995,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-new-products-0.jpg"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-new-products-0.jpg)

## How to configure the affiliate endpoint

To use this flow, the connector should provide an endpoint according to the standard:

`https://{endpointDoAfiliado}`

This endpoint should be configured in the VTEX affiliate registration page. Check out our [Configuring an Affiliate](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials%5F187) article.

## VTEX Notification

When creating a new product or SKU in VTEX a notification will be sent through the url configured in the section above. The table below presents the fields sent in this notification’s payload. The connector should use this data to implement the new product registration flow, described in the scenarios that will follow.

Fields sent in the notification:

| Name                                    | Description                                                                                |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| idSKU                                   | SKU ID in VTEX                                                                                |
| productId                               | Product ID in VTEX                                                                                |
| an                                      | Seller’s account name in VTEX, shown in the store’s VTEX Admin url.                                                                                |
| idAffiliate                             | Affiliate ID generated automatically in the configuration.                                                                                |
| DateModified                            | Date when the item was updated                                                                                |
| isActive                                | Identifies whether the product is active or not. In case it is “false”, it means the product was deactivated in VTEX and should be blocked in the marketplace. We recommend that the inventory level is zeroed in the marketplace, and the product is blocked. In case the marketplace doesn’t allow it to be deactivated, the product should be excluded, along with any existing correspondences in the connector. |
| StockModified                           | Identifies that the inventory level has been altered. Connectors should send an [Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) request to collect updated information.                                                                                |
| PriceModified                           | Identifies that the price has been altered. Connectors should send an [Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) request to collect updated information.                                                                                |
| HasStockKeepingUnitModified             | Identifies that the product/SKU registration data has changed, like name, description, weight, etc                                                                                |
| HasStockKeepingUnitRemovedFromAffiliate | Identifies that the product is no longer associated with the trade policy. In case the marketplace doesn’t allow it to be deactivated, the product should be excluded, along with any existing correspondences in the connector.                                                                                |

## Integration flow after notification

Follow the steps below, to send the initial load of products in the integration’s flow:

1. Connector validates the VTEX <> Marketplace authentication. In case it has expired, perform the update routine defined in the marketplace’s documentation. Otherwise, connectors should log the error AND put the VTEX notification in a contingency queue.
2. After receiving the VTEX notification, connectors should: a. Check which store the product belongs to, through the `an` parameter. b. If the `HasStockKeepingUnitModified` is defined as true, the product should be registered or updated in the marketplace. c. Collect details from every SKU using the [Get details of an SKU associated with a sales channel. ](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-sku)d. Validate if the product is active through the [Get Product by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-product) endpoint, through the `isActive` property. e. Validate if the product is associated with the trade policy used in the marketplace integration through the `salesChannel` property. f. Identify whether the SKU conforms to the marketplace’s product registration rules. g. Validate if the product’s category is mapped in the marketplace. In case it is not mapped, the marketplace should put the SKU in the approvement’s queue, until the [mapping](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper%23post-/api/mkp-category-mapper/categories/marketplace/-id-) is complete. h. Use [Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) (without postalCode) to check if price and inventory are configured in the selected trade policy.

If all validations pass, the product or SKU is sent to the marketplace and the operation is logged according to information described in the [Logs made available for users](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-logs%23log-messages) section.

If the IDs between VTEX and the marketplace differ, the connector should store both values. This information will be used for SKU [update](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-product-updates) operations.

### Recommendations

To avoid processing gaps due to the big volume of information of the initial load of products, we recommend:

* Using an async messaging architecture, using individual queues by context and store.
* Creating mechanisms that respect the marketplace API limit rates. We suggest the standard use of the _Circuit Breaker_ integration.
* In case any of the steps listed above presents failures in communication, we suggest using the contingency mechanism of _deadLetters_.
* Being TotalReader: whenever possible, in the data transformation process, using standard values accepted by the marketplace, in case the information is not filled or sent by VTEX.
* In case the marketplace’s processing is in lots - meaning that the connector assembles a group of SKUs, guaranteeing the the limit of records per lot is respected, according to marketplace riles, and sending them to the marketplace at once - it is fundamental to control the lot’s processing, to avoid sending SKU updates without making sure that the product exists in the marketplace.
* Keeping a states table to know which SKUs have not been integrated with success, attempt date and the response received. This allows the system to use the contingency flow effectively, avoiding infinite loops, and avoiding reaching the request limit.

> Make sure to check out our Recommendations for performing the steps above successfully. Be mindful to make all validations at once, and before the SKU’s publication in the marketplace’s catalog. In case there’s an error detected, the connector presents the seller a list of actions to correct. This way we can avoid the correct - publish - correct cycle.

If products do not apply to steps a, b and c, an error log must be filed, and the connector should collect the next items on the list obtained by step 2.

## API Reference

Use the endpoints described below to get SKU, price and inventory details. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token. You can also [download our Postman collection](https://read.calvincode.net/reader?url=https://www.getpostman.com/collections/95a809929905a50e2b7b) to access the API. The diagram illustrates the endpoints used in the integration:

![{"base64":"  ","img":{"width":12866,"height":8568,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":2399698,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-new-products-1.jpg"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-new-products-1.jpg)

> All parameters in the endpoints below must be declared in the request. In case one of the parameters does not have a value, you must still send it as `null`.[Get list of SKUs associated with a sales channel](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/get%5Fapi-catalog-system-pvt-sku-stockkeepingunitidsbysaleschannel)

[Get details of an SKU associated with a sales channel ](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-sku)

[Check if product is active](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-product)

[Simulate price and inventory levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation)

## Scenario 1: Register new product or SKU after notification

After receiving the VTEX notification of new product or SKU added `(HasStockKeepingUnitModified = true)`, connectors should:

1. Verify if the idSKU and idSkuMarketplace are mapped in the integration.
2. Verify if the SKU is already published in the marketplace.
3. If the conditions above are not met: register the new product in the marketplace.
4. Collect information about the SKU (weight, dimensions, etc).
5. Use the Orderform simulation to get price and inventory level, if needed.
6. Make the necessary data transformations.
7. Perform category mapping routines through VTEX Mapper. In case the mapping does not exist, log an error, and direct the message to the contingency queue, while logging and alerting the user about the error.
8. Make the necessary data transformations.
9. Send data to the marketplace. In case there’s a communication error, direct the message to the contingency queue.
10. If the call returns a success, they should create a correspondence table between the VTEX SkuId and Marketplace SkuId, to guarantee SKU [update](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-product-updates) operations.

> Make sure that all steps are logged as either success or failure, to offer the operation’s full traceability. Check out the [Logs made available for users](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-logs) page to learn more.

## What VTEX needs to validate the integration flow

To consider the integration validated by VTEX, the connector should:

1. Follow the step by step of the catalog integration flow.
2. Check if flows comply with the scenarios described.
3. Validate log messages contained in the table of Log’s [Content of the messages](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-order-logs%23content-of-the-messages).
4. Perform the performance test to validate response time, and SKU processing time from a set of 5000 SKUs.
5. Create tutorials for the final user (including text, videos and diagrams), including a step by step guide explaining how the connector created works. The documentation should be published in the production environment with easy access and navigation.
6. Create a table that explicits which data is mandatory and which is recommended when registering products or SKUs, and to improve the offer’s positioning in the marketplace’s storefront.
7. Create a table with known error logs and actions that the user can do to solve the problem.

> Tables should follow the format below. They will be implemented in the integration according to the connector’s documentation.

### Template table for field mapping {#template-table-for-field-mapping}

| VTEX field | How to fill it in VTEX | VTEX API                          | Marketplace field |
| ---------- | ---------------------- | --------------------------------- | ----------------- |
| Name       | Catalog page           | /api/catalog/pvt/stockkeepingunit | ShortName         |

Contributors

4

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

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

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

[Get product list for an initial load« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products//docs/guides/external-marketplace-integration-product-load)[How to get product updatesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products//docs/guides/external-marketplace-integration-product-updates)

Contributors

4

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

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

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

[How to configure the affiliate endpoint](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23how-to-configure-the-affiliate-endpoint)

[VTEX Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23vtex-notification)

[Integration flow after notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23integration-flow-after-notification)

[Recommendations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23recommendations)

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

[Scenario 1: Register new product or SKU after notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23scenario-1-register-new-product-or-sku-after-notification)

[What VTEX needs to validate the integration flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23what-vtex-needs-to-validate-the-integration-flow)

[Template table for field mapping {#template-table-for-field-mapping}](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23template-table-for-field-mapping-template-table-for-field-mapping)

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/external-marketplace-integration-guide/external-marketplace-integration-new-products.md)

Copy page

On this page

ON THIS PAGE

[How to configure the affiliate endpoint](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23how-to-configure-the-affiliate-endpoint)

[VTEX Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23vtex-notification)

[Integration flow after notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23integration-flow-after-notification)

[Recommendations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23recommendations)

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

[Scenario 1: Register new product or SKU after notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23scenario-1-register-new-product-or-sku-after-notification)

[What VTEX needs to validate the integration flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23what-vtex-needs-to-validate-the-integration-flow)

[Template table for field mapping {#template-table-for-field-mapping}](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-new-products/docs/guides/external-marketplace-integration-new-products%23template-table-for-field-mapping-template-table-for-field-mapping)

On this page

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


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

[User] Provide a guide on guides faststore organisms navbar in VTEX.

[Assistant]
Documentation

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

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

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

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

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

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

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

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

Storefront Development

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

---

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

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

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

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

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

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

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

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

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

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

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

[BannerText](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-banner-text)

[CartSidebar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-cart-sidebar)

[EmptyState](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-empty-state)

[FilterSlider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-filter-slider)

[Filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-filter)

[Hero](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-hero)

[ImageGallery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-image-gallery)

[NavbarSlider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar-slider)

[Navbar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar)

[Newsletter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-newsletter)

[OutOfStock](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-out-of-stock)

[PaymentMethods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-payment-methods)

[PriceRange](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-price-range)

[ProductGrid](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-product-grid)

[ProductShelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-product-shelf)

[RegionModal](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-region-modal)

[SearchInput](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-search-input)

[ShippingSimulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-shipping-simulation)

[SlideOver](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-slide-over)

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

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

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

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

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

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

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

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

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

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

---

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

---

(Legacy) CMS Portal

---

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

---

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

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

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

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

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

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

---

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

Storefront Development

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

---

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

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

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

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

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

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

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

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

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

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

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

[BannerText](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-banner-text)

[CartSidebar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-cart-sidebar)

[EmptyState](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-empty-state)

[FilterSlider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-filter-slider)

[Filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-filter)

[Hero](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-hero)

[ImageGallery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-image-gallery)

[NavbarSlider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar-slider)

[Navbar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar)

[Newsletter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-newsletter)

[OutOfStock](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-out-of-stock)

[PaymentMethods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-payment-methods)

[PriceRange](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-price-range)

[ProductGrid](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-product-grid)

[ProductShelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-product-shelf)

[RegionModal](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-region-modal)

[SearchInput](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-search-input)

[ShippingSimulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-shipping-simulation)

[SlideOver](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-slide-over)

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

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

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

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

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

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

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

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

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

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

---

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

---

(Legacy) CMS Portal

---

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

---

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

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

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

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

Navbar

Represents the page header and groups features like Search and Regionalization.

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

The `Navbar` represents the page header and groups some features like: `Search`, `Regionalization`, `SignIn`, `CartSidebar`. This component is part of the [Navigation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/feature-navigation) feature.

Uses `NavbarHeader`, `NavbarRow` and `NavbarButtons` as compound components.

The [NavbarLinks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/molecules-navbar-links) and [NavbarSlider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar-slider) components are used as child components.

Example

Code

Storefront

[Login](#)

Set location

* [Office](#)
* [Home Appliances](#)
* [Computer and Software](#)
* [Technology](#)

---

## Usage

### Import the component

`1

import { Navbar, NavbarHeader, NavbarRow, NavbarButtons } from '@faststore/ui'

`

### Import styles

To apply styles, include the following in your stylesheet:

`1

@import '@faststore/ui/src/components/organisms/Navbar/styles.scss';

`

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

---

## Design tokens

| Local token                      | Default value/Global token linked                         |
| -------------------------------- | --------------------------------------------------------- |
| \--fs-navbar-height-mobile       | 3.5rem                                                    |
| \--fs-navbar-bkg-color           | rgb(255 255 255 / 90%)                                    |
| \--fs-navbar-transition-timing   | var(--fs-transition-timing)                               |
| \--fs-navbar-transition-function | var(--fs-transition-function)                             |
| \--fs-navbar-box-shadow          | 0 var(--fs-spacing-0) var(--fs-spacing-3) rgb(0 0 0 / 5%) |

### Navbar Header

| Local token                                 | Default value/Global token linked            |
| ------------------------------------------- | -------------------------------------------- |
| \--fs-navbar-header-padding                 | 0 var(--fs-spacing-0)                        |
| \--fs-navbar-header-padding-top-notebook    | var(--fs-spacing-1)                          |
| \--fs-navbar-header-padding-bottom-notebook | var(--fs-navbar-header-padding-top-notebook) |

### Search

| Local token                                   | Default value/Global token linked                |
| --------------------------------------------- | ------------------------------------------------ |
| \--fs-navbar-search-button-icon-width-mobile  | var(--fs-spacing-5)                              |
| \--fs-navbar-search-button-icon-height-mobile | var(--fs-navbar-search-button-icon-width-mobile) |

### Search Expanded

| Local token                                           | Default value/Global token linked |
| ----------------------------------------------------- | --------------------------------- |
| \--fs-navbar-search-expanded-input-width              | calc(100% - var(--fs-spacing-7))  |
| \--fs-navbar-search-expanded-button-icon-margin-right | \-4.063rem                        |

### Logo

| Local token                         | Default value/Global token linked |
| ----------------------------------- | --------------------------------- |
| \--fs-navbar-logo-width             | var(--fs-logo-width)              |
| \--fs-navbar-logo-border-left-width | var(--fs-border-width)            |
| \--fs-navbar-logo-border-left-color | var(--fs-border-color-light)      |

---

## Data attributes

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

`data-fs-navbar`

`data-fs-navbar-header`

`data-fs-navbar-row`

`data-fs-navbar-buttons`

---

## Props

### Navbar

| Name                  | Type   | Description                                                                                | Default   |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------- | --------- |
| **testId**            | string | ID to find this component in testing tools (e.g.: Cypress, Testing Library, and Jest).            | fs-navbar |
| **scrollDirection\*** | string | Specifies the scroll direction. This value can be achieved using the \`useScrollDirection\` hook. |           |

### NavbarHeader

| Name       | Type   | Description                                                                            | Default          |
| ---------- | ------ | -------------------------------------------------------------------------------------- | ---------------- |
| **testId** | string | ID to find this component in testing tools (e.g.: Cypress, Testing Library, and Jest). | fs-navbar-header |

### NavbarRow

| Name       | Type   | Description                                                                            | Default       |
| ---------- | ------ | -------------------------------------------------------------------------------------- | ------------- |
| **testId** | string | ID to find this component in testing tools (e.g.: Cypress, Testing Library, and Jest). | fs-navbar-row |

### NavbarButtons

| Name                 | Type          | Description                                                                            | Default           |
| -------------------- | ------------- | -------------------------------------------------------------------------------------- | ----------------- |
| **testId**           | string        | ID to find this component in testing tools (e.g.: Cypress, Testing Library, and Jest). | fs-navbar-buttons |
| **searchExpanded\*** | false \| true | Specifies whether the Search Input is expanded or not.                                 |                   |

---

## Related components

* Open Menu
NavbarSlider
As part of the Navbar, this component it its mobile version used to list the navigation links.
[See more ](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar-slider)
* Set location
   * [Office](#)
   * [Home Appliances](#)
   * [Computer and Software](#)
   * [Technology](#)
NavbarLinks
Displays a set of navigation links.
[See more ](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/molecules-navbar-links)

Contributors

3

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

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

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

Was this helpful?

Yes

No

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

[NavbarSlider« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar-slider)[NewsletterNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-newsletter)

Contributors

3

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

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

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

ON THIS PAGE

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

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

[Design tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23design-tokens)

[Navbar Header](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbar-header)[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23search)[Search Expanded](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23search-expanded)[Logo](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23logo)

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

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

[Navbar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbar)[NavbarHeader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarheader)[NavbarRow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarrow)[NavbarButtons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarbuttons)

[Related components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23related-components)

Was this helpful?

 Send feedback

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

Copy page

On this page

ON THIS PAGE

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

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

[Design tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23design-tokens)

[Navbar Header](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbar-header)[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23search)[Search Expanded](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23search-expanded)[Logo](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23logo)

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

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

[Navbar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbar)[NavbarHeader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarheader)[NavbarRow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarrow)[NavbarButtons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23navbarbuttons)

[Related components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-navbar/docs/guides/faststore/organisms-navbar%23related-components)

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 search by geo coordinates 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/search-by-geo-coordinates/docs/guides)

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

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

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v2)

Schemas

Triggers

[Master Data v2 document saving flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v2-document-saving-flow)

[Creating relationships between data entities using Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/creating-relationships-between-data-entities-using-master-data-v2)

[Using dynamic expressions on Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/using-dynamic-expressions-on-master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2)

[Setting up alternate keys in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/setting-up-alternate-keys-in-master-data-v2)

[Setting up an auto increment field in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/setting-up-an-auto-increment-field-in-master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v1)

---

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/search-by-geo-coordinates/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides)

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/troubleshooting)

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v2)

Schemas

Triggers

[Master Data v2 document saving flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v2-document-saving-flow)

[Creating relationships between data entities using Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/creating-relationships-between-data-entities-using-master-data-v2)

[Using dynamic expressions on Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/using-dynamic-expressions-on-master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2)

[Setting up alternate keys in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/setting-up-alternate-keys-in-master-data-v2)

[Setting up an auto increment field in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/setting-up-an-auto-increment-field-in-master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v1)

---

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/search-by-geo-coordinates/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides)

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

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2)

Searching by geocoordinates in Master Data v2

To enable search by geocoordinates in Master Data v2, your JSON schema must contain an object with the properties `latitude` and `longitude`:

`1

{

2

"properties": {

3

 "{{yourFieldName}}": {

4

 "type": "object",

5

 "properties": {

6

 "latitude": { "type": "number" },

7

 "longitude": { "type": "number" }

8

 },

9

 "additionalProperties": false

10

 }

11

 }

12

}

`

Also, it must be configured as indexed:

`1

{

2

 "v-indexed": [ "{{yourFieldName}}" ]

3

}

`

## Saving documents

To save a document that can later be searched by geocoordinates, it must contain the object value configured as geocoordinates:

`1

{

2

 "{{yourFieldName}}": {

3

 "latitude": {{value}},

4

 "longitude": {{value}}

5

 }

6

}

`

## Filtering

To filter documents that contain a location nearby a given geocoordinate (measured in km), add a filter as a query parameter in this format:

`1

{{yourFieldName}}={{latitudeValue}},{{longitudeValue}},{{integer}}km

`

See an example:

`1

address.location=-23.01227,-43.46163,25km

`

## Ordering search results by distance

To order documents by distance from a given geocoordinate, use the `_sort` query parameter with this format:

`1

 _sort={{yourFieldName}} {{asc/desc}} {{latitudeValue}},{{longitudeValue}} km

`

See an example

`1

 _sort=address.location asc -23.01227,-43.46163 km

`

When Master Data order results by distance from a geocoordinate field a new field is available: `_sort`. This field could be added in `_fields` parameter to retrieve the distance between the geocoordinate in the sort query.

## Real complete example

JSON Schema:

`1

 {

2

 "properties": {

3

 "name": {

4

 "type": "string"

5

 },

6

 "isActive": {

7

 "type": "boolean"

8

 },

9

 "address": {

10

 "type": "object",

11

 "properties": {

12

 "state": {

13

 "type": "string"

14

 },

15

 "location": {

16

 "type": [

17

 "null",

18

 "object"

19

 ],

20

 "properties": {

21

 "latitude": {

22

 "type": "number"

23

 },

24

 "longitude": {

25

 "type": "number"

26

 }

27

 },

28

 "additionalProperties": false

29

 }

30

 }

31

 }

32

 },

33

 "v-indexed": [

34

 "name",

35

 "isActive",

36

 "address"

37

 ],

38

 "v-default-fields": [

39

 "id",

40

 "name",

41

 "address",

42

 "_sort"

43

 ]

44

 }

`

Query:

`1

 /search?address.location=-23.01227,-43.46163,100km&_schema=v1&_sort=address.location asc -23.01227,-43.46163 km&_fields=id,_sort

`

Result:

`1

 [

2

 {

3

 "id": "AME",

4

 "_sort": [

5

 0

6

 ]

7

 },

8

 {

9

 "id": "BAR",

10

 "_sort": [

11

 10.71936198115181

12

 ]

13

 },

14

 {

15

 "id": "BAN",

16

 "_sort": [

17

 14.87184710662879

18

 ]

19

 },

20

 {

21

 "id": "BRX",

22

 "_sort": [

23

 27.607623540300178

24

 ]

25

 }

26

 ]

`

Contributors

1

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Master-Data/master-data-v2/searching-by-geocoordinates-in-master-data-v2.md)

[Using dynamic expressions on Master Data v2« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates//docs/guides/using-dynamic-expressions-on-master-data-v2)[Setting up alternate keys in Master Data v2Next »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates//docs/guides/setting-up-alternate-keys-in-master-data-v2)

Contributors

1

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

[Saving documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23saving-documents)

[Filtering](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23filtering)

[Ordering search results by distance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23ordering-search-results-by-distance)

[Real complete example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23real-complete-example)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Master-Data/master-data-v2/searching-by-geocoordinates-in-master-data-v2.md)

Copy page

On this page

ON THIS PAGE

[Saving documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23saving-documents)

[Filtering](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23filtering)

[Ordering search results by distance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23ordering-search-results-by-distance)

[Real complete example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-by-geo-coordinates/docs/guides/searching-by-geocoordinates-in-master-data-v2%23real-complete-example)

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