[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 get a client profile by email 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/get-a-client-profile-by-email/docs/guides)

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

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

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

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-api-overview)

[Custom Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/custom-data-1)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/customization)

[Discounts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/discounts)

[Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/features)

[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/orders-2)

[Security](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-security)

[Shopping Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/shopping-cart-section-api-quick-start-guides)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/cart-attachments-section-api-quick-start-guides)

[Getting a customer profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email)

[Adding customer profile information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-customer-profile-information-to-the-cart)

[Add shipping address and select delivery option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-shipping-address-and-delivery-option-to-the-cart)

[Adding customer preferences to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-customer-preferences-to-the-cart)

[Adding marketing information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-marketing-information-to-the-cart)

[Add cart items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-cart-items)

[Adding payment information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/adding-payment-information-to-the-cart)

[Adding merchant context information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-merchant-context-information-to-the-cart)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/configuration-section-api-quick-start-guides)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/fulfillment-checkout-section-api-quick-start-guides)

[Region](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/region-section-api-quick-start-guides)

[Checkout error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-error-codes)

---

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

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-api-overview)

[Custom Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/custom-data-1)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/customization)

[Discounts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/discounts)

[Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/features)

[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/orders-2)

[Security](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-security)

[Shopping Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/shopping-cart-section-api-quick-start-guides)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/cart-attachments-section-api-quick-start-guides)

[Getting a customer profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email)

[Adding customer profile information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-customer-profile-information-to-the-cart)

[Add shipping address and select delivery option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-shipping-address-and-delivery-option-to-the-cart)

[Adding customer preferences to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-customer-preferences-to-the-cart)

[Adding marketing information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-marketing-information-to-the-cart)

[Add cart items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-cart-items)

[Adding payment information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/adding-payment-information-to-the-cart)

[Adding merchant context information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/add-merchant-context-information-to-the-cart)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/configuration-section-api-quick-start-guides)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/fulfillment-checkout-section-api-quick-start-guides)

[Region](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/region-section-api-quick-start-guides)

[Checkout error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-error-codes)

---

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

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/checkout-api-overview)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/cart-attachments-section-api-quick-start-guides)

[Getting a customer profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email)

Getting a customer profile by email

The shopping cart gathers information on the products the customer chooses while browsing a store, such as prices, shipping costs, payment methods, delivery methods, etc. This data may include item prices, shipping value, payment, and delivery methods, among others.

The information added to the customer profile can be used in the shopping cart to reduce the time the customer spends at Checkout and improve their shopping experience. For more information, read [Purchasing with SmartCheckout](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/smartcheckout-customer-information-automatic-fill-in--2Nuu3xAFzdhIzJIldAdtan%23purchasing-with-smartcheckout).

This guide will describe how to get client profile information using the email address registered in your store.

## Getting customer profile information

To access the customer profile information, you must use the [Get client profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getclientprofilebyemail) endpoint. In this request, you must send the customer's email through the URL address, as in the example below:

`https://{accountname}.{environment.com.br}/api/checkout/pub/profiles?email=test1@test2.com`

After sending the request, the endpoint will return the response body containing the client profile information, as in the example below:

`1

...

2

{

3

 "userProfileId": "fb542e51-5488-4c34-8d17-ed8fcf597a94",

4

 "profileProvider": "VTEX",

5

 "availableAccounts": [],

6

 "availableAddresses": [

7

 {

8

 "addressType": "residential",

9

 "receiverName": "Clark Kent",

10

 "addressId": "666c2e830bd9474ab6f6cc53fb6dd2d2",

11

 "isDisposable": false,

12

 "postalCode": "12345-000",

13

 "city": "Metropolis",

14

 "state": "NY",

15

 "country": "USA",

16

 "street": "My street",

17

 "number": "123",

18

 "neighborhood": "My neighborhood",

19

 "complement": null,

20

 "reference": null,

21

 "geoCoordinates": [

22

 -47.924747467041016,

23

 -15.832582473754883

24

 ]

25

 }

26

 ],

27

 "userProfile": {

28

 "email": "clark.kent@example.com",

29

 "firstName": "Clark",

30

 "lastName": "Kent",

31

 "document": "12345678900",

32

 "documentType": "cpf",

33

 "phone": "+556199999999",

34

 "corporateName": null,

35

 "tradeName": null,

36

 "corporateDocument": null,

37

 "stateInscription": null,

38

 "corporatePhone": null,

39

 "isCorporate": false,

40

 "profileCompleteOnLoading": null,

41

 "profileErrorOnLoading": null,

42

 "customerClass": null

43

 },

44

 "isComplete": true

45

}

46

...

`

>  Fields not completed in the customer profile will be displayed as `null`.

## Error codes

The following errors may appear as a message in the response body.

### 200 - OK

Despite the `200` code, which indicates the success of the request, if the email used is not registered in your store or the customer profile is invalid or incomplete, the response body will not contain any customer profile information. In these conditions, the [SmartCheckout](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/smartcheckout-customer-information-automatic-fill-in--2Nuu3xAFzdhIzJIldAdtan) feature cannot be used in the shopping cart.

`1

{

2

 "userProfileId": null,

3

 "profileProvider": null,

4

 "availableAccounts": [],

5

 "availableAddresses": [],

6

 "userProfile": null,

7

 "isComplete": false

8

}

`

### 400 - Bad Request

* **Message error example (code ORD002)**: `"Invalid order form"`. The `orderFormId` information is not valid.

`1

{

2

 "fields": {},

3

 "error": {

4

 "code": "ORD002",

5

 "message": "Invalid order form",

6

 "exception": null

7

 },

8

 "operationId": "5d9f54e6-7db4-46d6-bca9-deeb278b8b98"

9

}

`

### 404 - Not Found

* **Message error example**: `"The requested URL was not found on the server"`: Check if the URL is correct.

`1

2

404 Not Found

3

The requested URL was not found on this server.

4

`

Contributors

2

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

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/Checkout/cart-attachments-section-quick-start-guides/getting-a-customer-profile-by-email.md)

[Cart Attachments« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email//docs/guides/cart-attachments-section-api-quick-start-guides)[Adding customer profile information to the cartNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email//docs/guides/add-customer-profile-information-to-the-cart)

Contributors

2

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

ON THIS PAGE

[Getting customer profile information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23getting-customer-profile-information)

[Error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23error-codes)

[200 - OK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23200-ok)[400 - Bad Request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23400-bad-request)[404 - Not Found](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23404-not-found)

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/Checkout/cart-attachments-section-quick-start-guides/getting-a-customer-profile-by-email.md)

Copy page

On this page

ON THIS PAGE

[Getting customer profile information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23getting-customer-profile-information)

[Error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23error-codes)

[200 - OK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23200-ok)[400 - Bad Request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23400-bad-request)[404 - Not Found](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-a-client-profile-by-email/docs/guides/getting-a-customer-profile-by-email%23404-not-found)

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 getting started authentication 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/getting-started-authentication/docs/guides)

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

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

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

Guides

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

---

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

[List of REST APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/getting-started-list-of-rest-apis)

[Making your first request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/making-your-first-request)

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

[API authentication using API keys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-api-keys)

[Rotating VTEX API tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/rotating-vtex-api-tokens)

[App authentication using auth tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/app-authentication-using-auth-tokens)

[API authentication using user tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-user-tokens)

[Checking which user is currently authenticated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/checking-which-user-is-currently-authenticated)

[Expiring a shopper's password](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/expiring-a-shoppers-password)

[Refresh token flow for headless implementations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/refresh-token-flow-for-headless-implementations)

[Response status codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-response-codes)

Error handling and best practices

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

[List of REST APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/getting-started-list-of-rest-apis)

[Making your first request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/making-your-first-request)

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

[API authentication using API keys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-api-keys)

[Rotating VTEX API tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/rotating-vtex-api-tokens)

[App authentication using auth tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/app-authentication-using-auth-tokens)

[API authentication using user tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-user-tokens)

[Checking which user is currently authenticated](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/checking-which-user-is-currently-authenticated)

[Expiring a shopper's password](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/expiring-a-shoppers-password)

[Refresh token flow for headless implementations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/refresh-token-flow-for-headless-implementations)

[Response status codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-response-codes)

Error handling and best practices

---

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

---

Integration Guides

---

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

---

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

---

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

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

Authentication

Authentication is a crucial aspect of API integrations, backend, and frontend app development. It ensures authorized access by requiring valid credentials like API keys or tokens. This shields sensitive data, prevents breaches, and builds user trust. Get started with VTEX authentication for developers with the following guides:

* [API authentication using application keys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)
* [API authentication using user tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens)
* [App authentication using auth tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens)

There are different contexts in which authentication is required in the regular functioning of a VTEX store. Below are some example use cases and the recommended authentication methods.

| **Use case**                              | **Indicated authentication methods**                                                                                |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Backend VTEX IO app                       | [User token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) via VTEX IO context, or, if needed, [app authentication token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens) via VTEX IO context |
| Frontend VTEX IO app                      | [User token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) via VTEX IO context                                                                                |
| Self-hosted backend request to VTEX APIs  | [Application keys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)                                                                                |
| Self-hosted frontend request to VTEX APIs | [User token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens)                                                                                |

## Single sign on integrations

VTEX allows stores to integrate with external identity providers to provide single sign on (SSO) experiences to shoppers and Administrative users. You can learn more about this in the article [Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/login-integration-guide) and below you can find more information on these and other SSO use cases:

* [Store SSO with OAuth 2.0](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/login-integration-guide-webstore-oauth2)
* [Admin SSO with SAML 2.0](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/login-integration-guide-admin-saml2)
* [Use your VTEX account as an OAuth provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x)

## Learn more

* **Authorization**: [Users](https://read.calvincode.net/reader?url=https://help.vtex.com/en/subcategory/users--63DHe3VQEEE6Uuua8gIs2M), [Roles](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) and [License Manager Resources](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)
* **Auditability**: [Audit](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/searching-for-events-on-audit--5RXf9WJ5YLFBcS8q8KcxTA)

Contributors

2

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

Was this helpful?

Yes

No

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

[Making your first request« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication//docs/guides/making-your-first-request)[API authentication using API keysNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication//docs/guides/api-authentication-using-api-keys)

See also

[API authentication using API keysGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-api-keys)[API authentication using user tokensGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/api-authentication-using-user-tokens)[App authentication using auth tokensGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/app-authentication-using-auth-tokens)

Contributors

2

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

ON THIS PAGE

[Single sign on integrations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/authentication%23single-sign-on-integrations)

[Learn more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/authentication%23learn-more)

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/Getting-Started/authentication/authentication.md)

Copy page

On this page

ON THIS PAGE

[Single sign on integrations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/authentication%23single-sign-on-integrations)

[Learn more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication/docs/guides/authentication%23learn-more)

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 services 5 using the master data client 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/services-5-using-the-master-data-client/docs/guides)

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

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

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-service)

[Developing services on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/developing-services-on-vtex-io)

[1\. Getting started with the boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-1-getting-started-with-the-boilerplate)

[2\. Handling and receiving events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-2-handling-and-receiving-events)

[3\. Using the Analytics client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-3-using-the-analytics-client)

[4\. Using events as triggers](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-4-using-events-as-triggers)

[5\. Using the Master Data client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client)

[6\. Using GraphQL to retrieve data from Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-6-graphql-retrieving-data-from-master-data)

[7\. Using GraphiQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-7-using-graphiql)

[Services - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-conclusion)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-service)

[Developing services on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/developing-services-on-vtex-io)

[1\. Getting started with the boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-1-getting-started-with-the-boilerplate)

[2\. Handling and receiving events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-2-handling-and-receiving-events)

[3\. Using the Analytics client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-3-using-the-analytics-client)

[4\. Using events as triggers](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-4-using-events-as-triggers)

[5\. Using the Master Data client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client)

[6\. Using GraphQL to retrieve data from Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-6-graphql-retrieving-data-from-master-data)

[7\. Using GraphiQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-7-using-graphiql)

[Services - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-conclusion)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/app-development)

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/vtex-io-documentation-service)

[Developing services on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/developing-services-on-vtex-io)

[5\. Using the Master Data client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client)

5\. Using the Master Data client

Now that we are actively using the data retrieved from Analytics, the next crucial step is to persist and update this data. To achieve this, we'll leverage [Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/master-data), a database-as-a-service product from VTEX.

Master Data is the foundation for creating database architectures within a VTEX store. Initially designed for storing and organizing customer data, it has evolved into a versatile tool widely utilized by VTEX stores for business rule customizations and creating apps. The `@vtex/api` package provides a native Master Data client, accessible through `ctx.clients.masterdata`.

In this step, Master Data will be used to fetch data regarding the top N most viewed products, where N is a parameter that will be used to get the desired number of products.

Master Data uses the concept of data entities and [JSON Schema](https://read.calvincode.net/reader?url=https://spacetelescope.github.io/understanding-json-schema/) to validate and index documents. One _data entity_ can have many _schemas_, depending on how you need to use the data stored.

## Creating a Master Data entity

First, you will use the [Master Data API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/master-data-api-v2%23put-/api/dataentities/-dataEntityName-/schemas/-schemaName-) to create an entity and new schema in Master Data to save your product list. Use [Postman](https://read.calvincode.net/reader?url=https://www.postman.com/) or any other API client you prefer to send the cURL request presented in the right panel, providing the following information:

* `accountName`: Name of your VTEX account.
* `data_entity_name`: Name of the data entity to be created in Master Data. Use `course_backend_product_list` to be consistent with our app.
* `schema_name`: Name of the schema to be created in Master Data. Use `v1` to be consistent with our app (identical to the one used in `service-course-template/node/event/updateLiveUsers.ts`).
* `userToken`: Value of your user authentication cookie. To get your VTEX local token, run `vtex local token` in your terminal.

## Saving data to Master Data

Now, to save the data, we need to check if the `productSlug` is already saved in Master Data. Use the `searchDocuments` method of the Master Data client in the `node/event/liveUsersUpdate.ts` file, as highlighted in the provided code.

> Note: The `COURSE_ENTITY` global constant is `course_backend_product_list`, the name of our Master Data schema.

## Handling errors and exceptions

To ensure proper error handling, implement a `try-catch` structure, as presented in the code to the right.

## Updating existing documents

If a product is already saved, we need to update it by incrementing its count. The Master Data client provides the `createOrUpdateEntireDocument` method for this purpose. Implement the incrementation in the Master Data entity in the `liveUsersUpdate.ts` file, right after the `console.log({savedProduct})` line.

## Linking the app

Finally, run `vtex link` and wait for an event to be fired. Once it does, check your terminal for the logs in the code.

Break the `vtex link` by typing `ctrl + C` and use the provided cURL command to inspect the updates on Master Data. Replace `{{accountName}}` with your VTEX account name.

> To run a cURL on Windows, ensure to replace single quotes (`'`) with double quotes (`"`). For Windows versions earlier than Windows 10 (version 1803), [download and install cURL](https://read.calvincode.net/reader?url=https://curl.se/windows/).

cURL

`1

curl --location --request PUT 'https://{{accountName}}.vtexcommercestable.com.br/api/dataentities/{{data_entity_name}}/schemas/{{schema_name}}' \

2

--header 'Content-Type: application/json' \

3

--header 'VtexIdclientAutCookie: {{userToken}}' \

4

--data '{

5

 "properties": {

6

 "slug": {

7

 "type": "string"

8

 },

9

 "count": {

10

 "type": "number"

11

 }

12

 },

13

 "v-indexed": [

14

 "slug",

15

 "count"

16

 ],

17

 "v-security": {

18

 "allowGetAll": true,

19

 "publicRead": [

20

 "slug",

21

 "count"

22

 ],

23

 "publicWrite": [

24

 "slug",

25

 "count"

26

 ],

27

 "publicFilter": [

28

 "slug",

29

 "count"

30

 ]

31

 }

32

}'

`

Response

`1

{

2

 "Message": "JSON Schema persisted successfully. Revalidation and indexing process running in background."

3

}

`

Contributors

2

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

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/services/services-5-using-the-master-data-client.mdx)

[4\. Using events as triggers« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client//docs/guides/services-4-using-events-as-triggers)[6\. Using GraphQL to retrieve data from Master DataNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client//docs/guides/services-6-graphql-retrieving-data-from-master-data)

Contributors

2

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

ON THIS PAGE

[Creating a Master Data entity](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23creating-a-master-data-entity)

[Saving data to Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23saving-data-to-master-data)

[Handling errors and exceptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23handling-errors-and-exceptions)

[Updating existing documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23updating-existing-documents)

[Linking the app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23linking-the-app)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/services/services-5-using-the-master-data-client.mdx)

Copy page

On this page

ON THIS PAGE

[Creating a Master Data entity](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23creating-a-master-data-entity)

[Saving data to Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23saving-data-to-master-data)

[Handling errors and exceptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23handling-errors-and-exceptions)

[Updating existing documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23updating-existing-documents)

[Linking the app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/services-5-using-the-master-data-client/docs/guides/services-5-using-the-master-data-client%23linking-the-app)

On this page

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


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

[User] How do I use the VTEX store components 3.178.5 ProductBrand app? Provide documentation and configuration details.

[Assistant]
Documentation

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

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

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

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

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

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

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

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

Product Brand

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

Version: 3.178.5

Latest version: 3.178.5

The `product-brand` block displays either the **name** or the **logo** of a product's brand.

![{"base64":"  ","img":{"width":2854,"height":1578,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":661337,"url":"https://user-images.githubusercontent.com/52087100/70259346-bb081f80-176c-11ea-84db-5785c45829ce.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/52087100/70259346-bb081f80-176c-11ea-84db-5785c45829ce.png)

## Before you start

Ensure that you have registered [brands](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/what-is-a-brand--QU07yhHoaWcEYseEucOQW) in your store. To do so, follow the [How to register brands](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/registering-brands--tutorials%5F1414) documentation.

## Configuration

1. Import the `vtex.store-components` app to your theme's dependencies in the `manifest.json` file as in the following example:

`1

 "dependencies": {

2

 "vtex.store-components": "2.x"

3

 }

`

1. Add the `product-brand` block to any child of the `store.product` template (Product Details Page template). For example:

`1

 "store.product": {

2

 "children": [

3

 "flex-layout.row#product",

4

 ]

5

 },

6

 "flex-layout.row#product": {

7

 "children": [

8

+ "product-brand"

9

 ]

10

 },

`

1. Then, declare the `product-brand` block using the props stated in the [Props](#props) table. For example:

`1

"product-brand": {

2

 "props": {

3

 "displayMode": "text"

4

 }

5

 },

`

### Configuration

| Prop name          | Type             | Description                                                                                | Default value |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| brandId            | number           | The brand ID. If no value is declared, the product context should provide the data.                                                                                | undefined     |
| brandName          | string           | The brand name. If no value is declared, the product context should provide the data.                                                                                | undefined     |
| classes            | CustomCSSClasses | Overrides default CSS handles. To better understand how this prop works, check [this document](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/css-handles%23usecustomclasses). Note that this is only helpful if you're using this block as a React component.                                                                                | undefined     |
| displayMode        | string           | Defines if the product brand will be displayed by name or logo. Possible values are logo and text.                                                                                | logo          |
| excludeBrands      | array            | The brand names or brand IDs listed in the array will never be displayed by the Brand component. It is usually useful to hide default or test brand names/logos on the store front.                                                                                | undefined     |
| fallbackToText     | boolean          | Defines the behavior of the Product Brand block when set to display a brand logo but no image is registered in the VTEX admin's Catalog. If true, it allows the logo to be replaced with the brand name. If false, neither the brand name nor the brand logo are displayed. **This prop is only available for the logo display mode.**                                        | true          |
| height             | number           | The logo height. **This prop is only available for the logo display mode.**                                                                                | 100           |
| loadingPlaceholder | string           | Defines if the loading placeholder should have the size of the logo or the text. Possible values are: logo and text.                                                                                | undefined     |
| logoWithLink       | boolean          | ![{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAFUlEQVR4nGNoYGD6v3v+/6ask37WACanBhm9KoMJAAAAAElFTkSuQmCC","img":{"src":"https://img.shields.io/badge/-Deprecated-red","width":73,"height":20,"type":"svg"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/-Deprecated-red) Use withLink instead                                | false         |
| withLink           | enum             | Defines the scenarios in which the product brand should have a link that leads to its website. Possible values are: none (never includes the link), logo (includes the link whenever the brand logo is displayed), text (includes the link whenever the brand name is displayed), and logoAndText (includes the link whenever the brand logo or the brand name is displayed). | none          |

## Customization

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

| CSS Handles             |
| ----------------------- |
| productBrandContainer   |
| productBrandName        |
| productBrandLogo        |
| productBrandLogoWrapper |
| productBrandLogoLink    |
| productBrandNameLink    |
| productBrandLogoSpacer  |
| productBrandNameSpacer  |

See also

[Vtex.store ComponentsVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/ProductBrand/docs/apps/vtex.store-components)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Before you start](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/ProductBrand/docs/apps/vtex.store-components@3.178.5/ProductBrand%23before-you-start)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/ProductBrand/docs/apps/vtex.store-components@3.178.5/ProductBrand%23configuration)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/ProductBrand/docs/apps/vtex.store-components@3.178.5/ProductBrand%23configuration)

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

Was this helpful?

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


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

[User] Provide a guide on guides vtex shelf in VTEX.

[Assistant]
Documentation

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

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

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

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

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

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

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

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

Shelf

Official extension

Version: 1.49.0

Latest version: 1.49.0

> With the goal of displaying a flexible product list, the `shelf` and `shelf.relatedProducts` blocks are deprecated and now configured using the [Product Summary List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-summary-productsummarylist), the [Product Summary Shelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-summary), and the [Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-slider-layout) blocks. To learn how to configure it, please refer to [Building a Shelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-building-a-shelf).

The Shelf app displays a list of products on your store pages, helping you build your shop window and work on your visual merchandising.

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

## Configuration

1. Add the `shelf` app to your theme dependencies in the `manifest.json` file:

`1

 "dependencies": {

2

 "vtex.shelf": "1.x",

3

 }

`

Now, you can use all the blocks exported by the `shelf` app. See the full list below:

| Block name            | Description                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| shelf                 | ![{"base64":"  ","img":{"width":73,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/-Deprecated-red"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/-Deprecated-red) Renders a list of products in the store home page.              |
| shelf.relatedProducts | ![{"base64":"  ","img":{"width":73,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/-Deprecated-red"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/-Deprecated-red) Renders a list of related products in the product details page. |

1. Declare the `shelf.relatedProduct` in the product template (`store.product`) using its props. For example:

`1

{

2

 "store.product": {

3

 "children": [

4

 "breadcrumb",

5

 "flex-layout.row#main",

6

 "shelf.relatedProducts"

7

 ]

8

 }

9

}

`

> Warning
>
> Note that for hiding unavailable/out-of-stock items, there are 2 different props: `hideUnavailableItems` and `hideOutOfStockItems`. They do the same thing, but each is used by a different component: `Shelf` and `RelatedProducts`, respectively.

### Shelf

| Prop name                | Type              | Description                                                                                | Default value |
| ------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| category                 | String            | The category ID                                                                                |               |
| collection               | String            | The collection ID                                                                                |               |
| orderBy                  | Enum              | OrderByTopSaleDESC, OrderByPriceDESC, OrderByPriceASC, OrderByNameASC, OrderByNameDESC, OrderByReleaseDateDESC, OrderByBestDiscountDESC |               |
| hideUnavailableItems     | Boolean           | Whether out of stock items should be hidden (true) or not (false)                                                                       | false         |
| paginationDotsVisibility | Enum              | visible, hidden, mobileOnly, desktopOnly                                                                                |               |
| productList              | ProductListSchema | Product list schema. See ProductListSchema                                                                                | \-            |
| trackingId               | String            | Name to show in the Google Analytics. If nothing is passed it will use the name of the block instead                                    |               |
| maxItems                 | Number            | Max items                                                                                |               |

### RelatedProducts

| Prop name           | Type              | Description                                                                                | Default value |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| recommendation      | enum              | Type of recommendations that will be displayed on the shelf. Possible values: similars, suggestions, and accessories (these depend on the product information given in the Admin Catalog); and view, buy, and viewandBought (these are automatically generated according to the activity of the store). | similars      |
| groupBy             | enum              | Defines if you are ot nog going to group your recommendations by: PRODUCT (only display individual products and not SKUs, limited by 12 products) or NONE (if you want to display all registered SKUs, limited by 50 products).                                                                         | PRODUCT       |
| hideOutOfStockItems | boolean           | Whether out of stock items should be hidden: (true) or (false).                                                                                | false         |
| productList         | ProductListSchema | Product list schema. See ProductListSchema.                                                                                | \-            |

`ProductListSchema`:

| Prop name       | Type    | Description                                                                                | Default value |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| maxItems        | number  | Maximum number of items to be displayed on the related product shelf.                                                                                | 10            |
| scroll          | enum    | Slide transition scroll type. Possible values: BY\_PAGE, and ONE\_BY\_ONE.                                                                                | BY\_PAGE      |
| arrows          | boolean | Whether the arrows should be displayed on the shelf (true) or not (false).                                                                                | true          |
| showTitle       | boolean | Whether a title should be displayed on the product-related shelf (true) or not (false).                                                                                | true          |
| titleText       | string  | Related product shelf title.                                                                                | null          |
| gap             | enum    | Space between items being displayed. Possible values are: ph0, ph3,ph5, and ph7.                                                                                | ph3           |
| minItemsPerPage | number  | Minimum number of items per shelf slides. This prop defines how many items will be displayed on the related product shelf, even in the smallest screen size. Its value can be a float, which means that you can choose a multiple of 0.5 to indicate that you want to show a _peek_ of the next slide on the shelf. | 1             |
| itemsPerPage    | number  | Maximum number of items per shelf slides. This prop defines how many items will be displayed on the related product shelf, even in the largest screen size. Its value can be a float, which means that you can choose a multiple of 0.5 to indicate that you want to show a _peek_ of the next slide on the shelf.  | 5             |
| summary         | object  | Schema declaring the desired related product shelf items. This prop object must contain the [product-summary.shelf block props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-summary%23configuration).                                                                                | undefined     |
| ' infinite      | boolean | Determines whether the list should be infinite (true) or not (false). When this prop is set as false, the slider will have an explicit end for users.                                                                                | true          |

## Customization

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

| CSS Handles     |
| --------------- |
| relatedProducts |

> The CSS Handles list above refers to the `shelf.relatedProducts` block. Since the `shelf` block is deprecated, your shelf customization must be done using the CSS Handles available for the [Product Summary List](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-summary-productsummarylist), the [Product Summary Shelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-summary), and the [Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-slider-layout) blocks.

See also

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

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-shelf/docs/apps/vtex.shelf%23configuration)

[Shelf](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-shelf/docs/apps/vtex.shelf%23shelf)[RelatedProducts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-shelf/docs/apps/vtex.shelf%23relatedproducts)

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

Was this helpful?

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