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

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:

• Get schemas API endpoint: to check the schemas that are set up in your store for a given data entity.
• Save schema by name API endpoint: if you wish to create a schema for a given data entity.
• Schema lifecycle guide: to learn more.

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

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

Request body

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

Response

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

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

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

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"
}

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

PATCH

https://{accountName}.{envirnoment}.com.br/api/dataentities/CL/documents/{id}

Request body

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

Updating address request example

PATCH

https://{accountName}.{envirnoment}.com.br/api/dataentities/CL/documents/{id}

Request body

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