integrations.sh
← all integrations

vtex.local – Master-Data-API-

OpenAPI apis-guru

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:

  1. Directly from the storefront
  2. External integration

Directly from the storefront

If your scenario is to be used inside the storefront, be aware of the following observations:

  1. Use the storefront host to query or store information to avoid CORS;
  2. Configure which information should be public and which shouldn't, inside the JSON Schema of the Data Entity;
  3. Do not create query loops (the storefront may be affected with Throttling and apis may be turned off as a security protection);
  4. 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:

  1. Use the host {{accountName}}.vtexcommercestable.com.br;
  2. Use the authentication keys (x-vtex-api-appkey ou x-vtex-api-apptoken);

Most used attributes listed here

NameDescription
accountNameAccount name in VTEX License Manager
nameData Entity name
schemaJSON Schema of a Data Entity
idIdentifier of a document
x-vtex-api-appKeyUser key
x-vtex-api-appTokenUser token
Homepage
https://api.apis.guru/v2/specs/vtex.local:Master-Data-API-/1.0.json
Provider
vtex.local:Master-Data-API- / Master-Data-API-
OpenAPI version
3.0.0
Spec (JSON)
https://api.apis.guru/v2/specs/vtex.local/Master-Data-API-/1.0/openapi.json
Spec (YAML)
https://api.apis.guru/v2/specs/vtex.local/Master-Data-API-/1.0/openapi.yaml

Tools (28)

Extracted live via the executor SDK.

  • addresses.createNewCustomerAddress

    Creates 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 using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use .

  • addresses.deleteCustomerAddress

    Deletes a customer address.

  • addresses.updateCustomerAddress

    Partially updates a customer address.

    You can use this request to update customer addresses according to any AD schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use .

  • clusters.validatedocumentbyclusters

    Check if a document is present in one or more clusters (specific set of field values).

    There is a limit of five rules per request.

  • customerProfiles.createNewCustomerProfilev2

    Creates 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 using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use .

  • customerProfiles.deleteCustomerProfile

    Deletes a customer profile.

  • customerProfiles.updateCustomerProfile

    Partially updates a customer profile.

    You can use this request to update customer profiles according to any CL schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use .

  • documents.createnewdocument

    This 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 can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to create.

    Example use cases

    Client profile

    In order to create a new customer profile, choose the CL data entity and send a request similar to this:

    POST

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents

    Request body

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

    Client address

    For a new address, the data entity is AD and the request would look like this:

    POST

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents

    Request body

    json
    {    "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"}
  • documents.createorupdatepartialdocument

    This 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 entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.

    Example use cases

    Client profile

    In order to create a customer profile's phone and isNewsletterOptIn fields, choose the CL data entity and send a request similar to this:

    PATCH

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents

    Request body

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

    Client address

    In order to update the receiverName of an existing address, the data entity is AD and the request would look like this:

    PATCH

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents

    Request body

    json
    {    "receiverName": "Lois Lane"}
  • documents.deletedocument

    It allows to delete a document.

  • documents.getdocument

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

  • documents.updateentiredocument

    Update 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 update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.

    Example use cases

    Client profile

    In order to update an existing customer profile, choose the CL data entity and send a request similar to this:

    PUT

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents/123456789abc

    Request body

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

    Client address

    To update an address, the data entity is AD and the request would look like this:

    PUT

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents/123456789abc

    Request body

    json
    {    "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"}
  • documents.updatepartialdocument

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

    You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.

    Example use cases

    Client profile

    In order to update a customer profile's phone and isNewsletterOptIn fields, choose the CL data entity and send a request similar to this:

    PATCH

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents/123456789abc

    Request body

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

    Client address

    In order to update the receiverName of an existing address, the data entity is AD and the request would look like this:

    PATCH

    https://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents/123456789abc

    Request body

    json
    {    "receiverName": "Lois Lane"}
  • indices.deleteindexbyname

    Delete an index.

  • indices.getindexbyname

    Returns an index.

  • indices.getindices

    Returns the list of indices by data entity.

  • indices.putindices

    Create an index.

  • schemas.deleteschemabyname

    Deletes an existing schema for a given data entity.

  • schemas.getschemabyname

    Returns an existing schema for a given data entity.

  • schemas.getschemas

    Return the schemas saved.

  • schemas.saveschemabyname

    Creates or edits a data entity schema. Learn more about

    Note that if you send a schemaName that does not exist for that data entity, this request will create it.

    This request can also be used to .

  • scroll.scrolldocuments

    In 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 parameter. The token has a timeout of 10 minutes, which refreshes after each request.

    After the token is obtained it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.

    Avoid sending too many requests with wildcards (*) in the search parameters or that use the keyword parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code 429.

    Request examples

    First request:

    /dataentities/Client/scroll?isCluster=true&_size=250&_fields=email,firstName

    Retrieve the token in the header X-VTEX-MD-TOKEN from the first request's response and use it to make the next requests.

    Subsequent requests:

    /dataentities/Client/scroll?_token={tokenValueExample}
  • search.searchdocuments

    Retrieves documents' information, while choosing which fields will be returned and filtering documents by specific fields.

    The response header REST-Content-Range indicates the total amount of results for that specific search. For example, it may return resources 0-100/136108, which indicates it has returned results from 0 to 100 of a total 136108.

    Below you can see some query examples and learn more about each query parameter.

    Avoid sending too many requests with wildcards (*) in the search parameters or that use the keyword parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code 503.

    Query examples

    Simple filter

    /dataentities/Client/search?email=my@email.com

    Complex filter

    /dataentities/Client/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)

    Date Range

    /dataentities/Client/search?_where=createdIn between 2001-01-01 AND 2016-01-01

    Range numeric fields

    /dataentities/Client/search?_where=age between 18 AND 25

    Partial filter

    /dataentities/Client/search?firstName=*Maria*

    Filter for null values

    /dataentities/Client/search?_where=firstName is null

    Filter for non-null values

    /dataentities/Client/search?_where=firstName is not null

    Filter for difference

    /dataentities/Client/search?_where=firstName<>maria

    Filter greater than or less than

    /dataentities/Client/search?_where=number>5/dataentities/Client/search?_where=date<2001-01-01
  • versions.getversion

    Returns the version of a document.

  • versions.listversions

    Allows to list the versions of a document.

  • versions.putversion

    Updates document with version values.

  • openapi.previewSpec

    Preview an OpenAPI document before adding it as a source

  • openapi.addSource

    Add an OpenAPI source and register its operations as tools