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

The Checkout module stores shopper data in Master Data v1 by default. Because of this, using the Master Data v1 API is the best way to integrate your customer database into 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

Master Data v1 leverages the concept of data entities to allow for highly customizable databases. 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: shopper profiles.
• AD: shopper addresses.

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

• creating new customer profiles.
• creating addresses.

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

• Retrieve customer data.
• Edit customer data.

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

POST

Request body

Response

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

POST

Request body

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.

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 v1 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.

Request body

Request body