API Reference

Integration Guides
Headless commerce
Headless profile management and order history

Profile management is an important feature, that allows shoppers in your store to view and edit their personal information, as well as order history and other features.

VTEX's native storefront accomplishes this with the My account page, but below you can learn how to use VTEX APIs to build the same features in your headless shopping experience.

Profile management

Regarding profile management, your integration must be able to access profile information, edit profile information and also perform password resets.

Accessing profile information

The best way to retrieve shopper profile information on your headless storefront is to use this endpoint of the Checkout API:

By default, this endpoint returns only complete profiles, but you may use the boolean query parameter ensureComplete=false to get incomplete profiles as well.

A complete profile includes all information necessary to place an order: email, firstName, lastName, phone, document, and an associated address with all required fields.

Editing profile information

VTEX uses Master Data v1 to store and manage shopper information. So in order to manage profile data from your storefront, you must use the Master Data v1 API.

Learn more about Master Data and its basic components.

In Master Data v1, shopper profiles are documents in the CL data entity, while addresses are documents in the AD data entity. See below the endpoints for managing Master Data v1 documents:

If you prefer to search shopper information by other information, such as email address, instead of the document ID, use the search endpoint:


Currently, there is no way to edit shoppers' passwords from a headless frontend. However, you can implement password expiration, so that your customers can then go to your store and create a new password.

To implement this feature, follow the instructions in the guide Expiring a shopper's password.

This method of password expiration does not trigger any notification. You must notify the shopper that they must create a new password on your website. Learn more about Shopper authentication for headless stores.

News letter subscription

When shoppers go to the profile management section of your store, they may wish to manage their consent of newsletter subscription. For this purpose, note that this information is in the shopper profile, in the boolean field named isNewsletterOptIn.

Order history

You can use the endpoints below to fetch order information related to a specific shopper.

Actions on existing orders

Some stores allow shoppers to request changes or even the cancellation of existing orders. For order cancelation, use this endpoint:

For requesting changes to an existing order, you can use the endpoint below, but see the Change order guide to learn more about this process.

Learn more

See these other guides to learn more about building a headless shopping experience using VTEX:

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page