inStore is VTEX’s core product for Unified Commerce operations. It allows your store to deliver a real omnichannel experience by seamlessly integrating your online and in-store channels and having your clients in the core of your business.

When setting inStore in your business, you might need to add physical stores and sales associates to the system, as well as managing existing stores and sales associates. You can do this by using VTable, as described in this article, or you can use the Master Data API - V2, as described below.

If you want to create a new physical store on inStore, you should use the Create new document or the Update entire document endpoints with the params listed below.

The request body should have the following properties:

Request body example:

{
  "codes": [
    {
      "code": "{\n  \"name\": \"Botafogo Store\",\n  \"mobileNumber\": \"9999999999\",\n  \"pickupPoint\": \"1098765\",\n  \"franchiseAccount\": \"franchise1\",\n  \"postalCode\": \"222222\",\n  \"tradePolicy\": \"1\",\n  \"country\": \"BRA\",\n  \"state\": \"Rio de Janeiro\",\n  \"city\": \"Rio de Janeiro\",\n  \"neighborhood\": \"Botafogo\",\n  \"address\": \"Praia de Botafogo\",\n  \"number\": \"300\",\n  \"complement\": \"3rd floor\"\n}",
      "language": "json"
    }
  ]
}

When the request is successful, the response is a json schema including a new DocumentId attribute, which represents the store ID number:

{
  "codes": [
    {
      "code": "{\n    \"Id\": \"stores-16aa42c4-f489-11eb-82ac-0ea70a628d87\",\n    \"Href\": \"http://accountname.vtexcommercestable.com.br/api/dataentities/stores/documents/16aa42c4-f489-11eb-82ac-0ea70a628d87?_schema=v1\",\n    \"DocumentId\": \"16aa42c4-f489-11eb-82ac-0ea70a628d87\"\n}",
      "language": "json"
    }
  ]
}

To update store information, you can use the same request you would use to Create a store, but including the id field in the request body and changing any attribute you want:

Request body example (changing the mobileNumber):

{
  "codes": [
    {
      "code": "{\n  \"id\": \"16aa42c4-f489-11eb-82ac-0ea70a628d87\",\n  \"name\": \"Botafogo Store\",\n  \"mobileNumber\": \"888888888\",\n  \"pickupPoint\": \"1098765\",\n  \"franchiseAccount\": \"franchise1\",\n  \"postalCode\": \"222222\",\n  \"tradePolicy\": \"1\",\n  \"country\": \"BRA\",\n  \"state\": \"Rio de Janeiro\",\n  \"city\": \"Rio de Janeiro\",\n  \"neighborhood\": \"Botafogo\",\n  \"address\": \"Praia de Botafogo\",\n  \"number\": \"300\",\n  \"complement\": \"3rd floor\"\n}",
      "language": "json"
    }
  ]
}

Response body example:

{
  "codes": [
    {
      "code": "{\n    \"Id\": \"stores-16aa42c4-f489-11eb-82ac-0ea70a628d87\",\n    \"Href\": \"http://accountname.vtexcommercestable.com.br/api/dataentities/stores/documents/16aa42c4-f489-11eb-82ac-0ea70a628d87?_schema=v1\",\n    \"DocumentId\": \"16aa42c4-f489-11eb-82ac-0ea70a628d87\"\n}",
      "language": "json"
    }
  ]
}

In case you need to find an existing physical store to check their ID or other information, you should use the Search documents endpoint. You can use any other query params you want in this request.

In order to delete a physical store and remove its data in Master Data, you should use the Delete document endpoint.

If you want to create a new sales associate on inStore, you should use the Create new document or the Update entire document endpoints. Using this request, you will give the sales associate access to inStore and automatically give them the inStore Sales Person role in your account.

The request body should have the following properties:

Request body example:

{
  "codes": [
    {
      "code": "{\n  \"name\": \"Jane Doe\",\n  \"user\": \"jane@email.com\",\n  \"code\": \"123456\",\n  \"store\": \"16aa42c4-f489-11eb-82ac-0ea70a628d87\"\n}",
      "language": "json"
    }
  ]
}

When the request is successful, the response is a json including a new DocumentId attribute, which represents the sales associate ID number:

{
  "codes": [
    {
      "code": "{\n    \"Id\": \"vendors-d74145dc-f494-11eb-82ac-1271e6f73475\",\n    \"Href\": \"http://accountname.vtexcommercestable.com.br/api/dataentities/vendors/documents/d74145dc-f494-11eb-82ac-1271e6f73475?_schema=v1\",\n    \"DocumentId\": \"d74145dc-f494-11eb-82ac-1271e6f73475\"\n}",
      "language": "json"
    }
  ]
}

To update sales associate information, you can use the same request you would use to Create a sales associate, but including the id field in the request body:

Request body example:

{
  "codes": [
    {
      "code": "{\n  \"id\": \"d74145dc-f494-11eb-82ac-1271e6f73475\",\n  \"name\": \"Jane Doe\",\n  \"user\": \"jane.doe@email.com\",\n  \"code\": \"123456\",\n  \"store\": \"16aa42c4-f489-11eb-82ac-0ea70a628d87\",\n}",
      "language": "json"
    }
  ]
}

Response body example:

{
  "codes": [
    {
      "code": "{\n    \"Id\": \"vendors-d74145dc-f494-11eb-82ac-1271e6f73475\",\n    \"Href\": \"http://accountname.vtexcommercestable.com.br/api/dataentities/vendors/documents/d74145dc-f494-11eb-82ac-1271e6f73475?_schema=v1\",\n    \"DocumentId\": \"d74145dc-f494-11eb-82ac-1271e6f73475\"\n}",
      "language": "json"
    }
  ]
}

In case you need to find an existing sales associate to check their ID or other information, you should use the Search documents endpoint. You can use any other query params you want in this request. The response body will contain information about the sales associate and the store they are associated with.

In order to delete a sales associate and remove their data in Master Data, you should use the Delete document endpoint.