Documentation
Feedback
Guides
API Reference

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

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

Data entities

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.

Integration

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

POST


_10
https://{accountName}.{environment}.com.br/api/dataentities/CL/documents

Request body


_11
{
_11
"email": "clark.kent@examplemail.com",
_11
"firstName": "Clark",
_11
"lastName": "Kent",
_11
"phone": "+12025550195",
_11
"documentType": "CPF",
_11
"document": "12345678900",
_11
"isCorporate": false,
_11
"isNewsletterOptIn": false,
_11
"localeDefault": "en-US"
_11
}

Response


_10
{
_10
"Id": "CL-b345cbda-e489-11e6-94f4-0ac138d2d42e",
_10
"Href": "http://api.vtex.com/my-store-name/dataentities/CL/documents/b345cbda-e489-11e6-94f4-0ac138d2d42e"
_10
}

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

POST


_10
https://{accountName}.{environment}.com.br/api/dataentities/AD/documents

Request body


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

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

Updating customer profile request example


_10
PATCH
_10
https://{accountName}.{environment}.com.br/api/dataentities/CL/documents/{id}

Request body


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

Updating address request example


_10
PATCH
_10
https://{accountName}.{environment}.com.br/api/dataentities/AD/documents/{id}

Request body


_10
{
_10
"street": "Market Street",
_10
"neighborhood": "South side",
_10
"number": "27",
_10
}

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