Master Data API - v2
ATTENTION: This version isn't compliant with data entities of old version (e.g. CL and AD). It's possible to use this configuration only to new data entities.…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
ATTENTION: This version isn't compliant with data entities of old version (e.g. CL and AD). It's possible to use this configuration only to new data entities.
Welcome!
VTEX Master Data is an easy-to-use, secure, fast, scalable and extensible repository. On it you can create your own Entities, store data and consult directly from the storefront or use it to store info for some external integration.
There are internal VTEX modules that use VTEX Master Data as data repository. We have the VTEX Customer Service, VTEX Profile System and VTEX InStore, for example. It is also used by other internal services.
There are two ways to use Master Data:
- Directly from the storefront
- External integration
Directly from the storefront
If your scenario is to be used inside the storefront, be aware of the following observations:
- Use the storefront host to query or store information to avoid CORS;
- Configure which information should be public and which shouldn't, inside the JSON Schema of the Data Entity;
- Do not create query loops (the storefront may be affected with Throttling and apis may be turned off as a security protection);
- Never add via JS any type of authentication key (x-vtex-api-appkey or x-vtex-api-apptoken);
It's important to avoid CORS using the relative path
External Integration
If your scenario is to perform external integration, such as migrating client data from another service, be aware of the following observations:
- Use the host
{{accountName}}.vtexcommercestable.com.br; - Use the authentication keys (x-vtex-api-appkey ou x-vtex-api-apptoken);
Most used attributes listed here
| Name | Description |
|---|---|
| accountName | Account name in VTEX License Manager |
| name | Data Entity name |
| schema | JSON Schema of a Data Entity |
| id | Identifier of a document |
| x-vtex-api-appKey | User key |
| x-vtex-api-appToken | User token |
Endpoints 26
Documents
- POSTCreate new document
/api/dataentities/:dataEntityName/documents?_schema=schemaThis request allows you to create a new document corresponding to a given data entity. For example, you can create a new customer profile or address. > You… - PATCHCreate partial document
/api/dataentities/:dataEntityName/documents?_schema=schemaThis request allows you to partially update a document corresponding to a given data entity. > You can use this request to create documents for any given data… - GETGet document
/api/dataentities/:dataEntityName/documents/:idGets document by ID. > Assign the _fields parameter in the query string to retrieve the desired fields. If you want to return all the fields use _fields=_all. - PUTUpdate entire document
/api/dataentities/:dataEntityName/documents/:id?_where=firstName is not null.&_schema=schemaUpdate an existing document corresponding to a given data entity. For example, you can update a customer profile or address. > You can use this request to… - DELETEDelete document
/api/dataentities/:dataEntityName/documents/:idIt allows to delete a document. - PATCHUpdate partial document
/api/dataentities/:dataEntityName/documents/:id?_where=firstName is not null.&_schema=schemaThis request allows you to partially update a document corresponding to a given data entity. For example, you can update some fields of a customer profile or…
Search
- GETSearch documents
/api/dataentities/:dataEntityName/search?_fields=email,firstName,document&_where=firstName is not null.&_schema=schema&_keyword=String to search&_sort=firstName ASCRetrieves documents' information, while choosing which fields will be returned and filtering documents by specific fields. > The response header…
Scroll
- GETScroll documents
/api/dataentities/:dataEntityName/scroll?_token={tokenValueExample}&_fields=email,firstName,document&_where=firstName is not null.&_schema=schema&_keyword=String to search&_sort=firstName ASCIn the first request, the X-VTEX-MD-TOKEN token will be returned in the header. This token must be passed to the next request in the query string _token…
Schemas
- GETGet schemas
/api/dataentities/:dataEntityName/schemasReturn the schemas saved. - GETGet schema by name
/api/dataentities/:dataEntityName/schemas/:schemaNameReturns an existing schema for a given data entity. - PUTSave schema by name
/api/dataentities/:dataEntityName/schemas/:schemaNameCreates or edits a data entity schema. Learn more about Master Data schemas > Note that if you send a schemaName that does not exist for that data entity,… - DELETEDelete schema by name
/api/dataentities/:dataEntityName/schemas/:schemaNameDeletes an existing schema for a given data entity.
Indices
- GETGet indices
/api/dataentities/:dataEntityName/indicesReturns the list of indices by data entity. - PUTPut indices
/api/dataentities/:dataEntityName/indicesCreate an index. - GETGet index by name
/api/dataentities/:dataEntityName/indices/:index_nameReturns an index. - DELETEDelete index by name
/api/dataentities/:dataEntityName/indices/:index_nameDelete an index.
Clusters
- POSTValidate document by clusters
/api/dataentities/:dataEntityName/documents/:id/clustersCheck if a document is present in one or more clusters (specific set of field values). > There is a limit of five rules per request.
Versions
- GETList versions
/api/dataentities/:dataEntityName/documents/:id/versions?load=true&fields=id,dataEntityId,isNewsletterOptIn,createdByAllows to list the versions of a document. - GETGet version
/api/dataentities/:dataEntityName/documents/:id/versions/:versionIdReturns the version of a document. - PUTPut version
/api/dataentities/:dataEntityName/documents/:id/versions/:versionIdUpdates document with version values.
Customer profiles
- POSTCreate new customer profile
/api/dataentities/Client/documents?_schema=schemaCreates new customer profile. > You can use this request to create customer profiles according to any CL schema. Because of this, you are not restricted to… - DELETEDelete customer profile
/api/dataentities/Client/documents/:idDeletes a customer profile. - PATCHUpdate customer profile
/api/dataentities/Client/documents/:id?_schema=schemaPartially updates a customer profile. > You can use this request to update customer profiles according to any CL schema. Because of this, you are not…
Addresses
- POSTCreate new customer address
/api/dataentities/Address/documents?_schema=schemaCreates new customer address. > You can use this request to create customer addresses according to any AD schema. Because of this, you are not restricted to… - DELETEDelete customer address
/api/dataentities/Address/documents/:idDeletes a customer address. - PATCHUpdate customer address
/api/dataentities/Address/documents/:id?_schema=schemaPartially updates a customer address. > You can use this request to update customer addresses according to any AD schema. Because of this, you are not…
API details
- Base URL
https://vtex.localhttps://{accountName}.{environment}.com.br- Authentication
- An API key in the X-VTEX-API-AppKey header
An API key in the X-VTEX-API-AppToken header - Operations
- 26 operations on 15 pathsGET 9DELETE 5PUT 4POST 4PATCH 4
- Main resources
- Documents 6Indices 4Schemas 4Addresses 3Customer profiles 3Versions 3Clusters 1Scroll 1Search 1
- Response formats
application/json- Description format
- OpenAPI 3.0.0, API version
1.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Master Data API - v2 in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Master Data API - v2 collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-VTEX-API-AppKey header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Create new document” (POST /api/dataentities/:dataEntityName/documents?_schema=schema), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Master Data API - v2?
ATTENTION: This version isn't compliant with data entities of old version (e.g. CL and AD). It's possible to use this configuration only to new data entities.… It is listed under Other and has 26 endpoints.
Who publishes the Master Data API - v2?
It is listed from VTEX's public API description (an OpenAPI document), not published by VTEX on Swastik Codes. Anyone who controls vtex.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Master Data API - v2?
Its description lists 2 base URLs: https://vtex.local, https://{accountName}.{environment}.com.br. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Master Data API - v2?
It accepts 2 methods: an API key in the X-VTEX-API-AppKey header; an API key in the X-VTEX-API-AppToken header.
How many endpoints does the Master Data API - v2 have?
26 operations on 15 paths (9 GET, 5 DELETE, 4 PUT, 4 POST, 4 PATCH). The largest groups are Documents, Indices, Schemas, Addresses.
Is forking the Master Data API - v2 free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.