API Reference

Integration Guides
Headless commerce

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

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

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

{"base64":"  ","img":{"width":4636,"height":3450,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":809205,"url":""}}

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


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

We recommend you also learn more about:

Authenticating shopper identity

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

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

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


  1. Once the shopper has successfully logged in, VTEX will set a user token in a cookie named VtexIdclientAutCookie.
  2. Store this user token. You must use it to authenticate API requests.

Authenticating requests to VTEX APIs

There are different machine authentication methods available for you to authenticate your integration's requests to VTEX APIs.

For the purpose of headless stores, we recommend using user tokens whenever possible. You can obtain this token as indicated in the section Authenticating shoppers' identity.

You can also use application keys in contexts where shoppers authentication is not necessary, such as product search.

Shopping experience

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

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