API Reference

Integration Guides
Back office integration guide (ERP/PIM/WMS)
Import customer data

When implementing an ecommerce project, it may be necessary to import customer data from other systems, such as Customer Relationship Management (CRM) applications.

You can use Master Data v2 to manage many types of data and it provides the best way of integrating your customer data base to VTEX.

In this guide, you can learn how to import customer data to VTEX. Learn more about Master Data and its features in the Master Data developers guide.

Importing your customers' data will also enable automatic fill-in at checkout for those customers. Learn more about SmartCheckout - Customer information automatic fill-in

Data entities

Master Data v2 leveradges the concept of data entities to allow for highly customizable data bases. These work as tables, where each document (profile or address) is saved as a row.

There are two native data entities you must use for this integration:

  • CL: stores customer profiles.
  • AD: stores addresses.


It is not strictly necessary, but you can use JSON schemas, to specify the format of the data you expect to store. By using them you enable some handy features such as:

  • Indicating which fields are searchable.
  • Having Master Data validate documents as they are sent.
  • Master Data triggers.

    A single data entity may be associated with more than one schema and will store documents that comply with multiple schemas or none.

To implement schemas, check:


The basic operations you will need to import customer data are:

Depending on your project’s architecture, it may also be important to:

Create new customer profile

To register a new customer profile, use the Create new document for the CL data entity.

When creating a new document, you will receive an Id in the response. This identifies the customer in Master Data and will be used later to register addresses associated with that customer. Make sure you save this ID and associate it with the customer’s ID in your source database.

Creating customer profile request example



Request body

{ "email": "", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" }


{ "Id": "CL-b345cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "" }

Create new address

To register a new customer address, use the Create new document for the AD data entity.

Note that the userId in the request body is the Id returned by the API when creating a customer profile. Make sure to send it to associate the address with the corresponding customer.

Creating new address request example



Request body

{ "addressName": "My House", "addressType": "residential", "city": "Metropolis", "complement": "", "country": "USA", "postalCode": "11375", "receiverName": "Clark Kent", "reference": null, "state": "MP", "street": "Baker Street", "neighborhood": "Upper east side", "number": "21", "userId": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e" }

Retrieve customer data

If you need to retrieve customer information after you have imported it to VTEX, you can use one of these endpoints:

  • Search documents: more direct solution for fetching a single document, while also being able to return multiple results.
  • Scroll documents: useful if you want to fetch multiple documents spread across multiple requests.

These requests allow you to filter and sort data by any of the documents’ fields. You can also request that only certain pieces of information be returned, instead of the complete documents. See Search documents and Scroll documents to learn more.

Edit customer data

Once your store is up and running, your customers can update their profile information in the My Account section and it will be automattically updated in the documents you have created with the Master Data v2 API. So many integrations will not have to deal with customer data maintenance.

However, if you need to implement such an integration, you can use the Update partial document API endpoint.

Updating customer profile request example



Request body

{ "phone": "+12025550195", "isNewsletterOptIn": false }

Updating address request example



Request body

{ "phone": "+12025550195", "isNewsletterOptIn": false }
Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Import inventory
« Previous
Set up order integration
Next »
Photo of the contributor
+ 1 contributors
On this page