Create and manage physical stores and sales associates in Master Data

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.


Stores


Create a store

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

ParamValue
data_entity_namestores
_schemav1

The request body should have the following properties:

AttributeTypeDescription
namestringStore name
mobileNumberstringStore phone number
pickupPointstringStore pickup point ID number
franchiseAccountstringFranchise account name
postalCodestringStore postal code
tradePolicystringTrade Policy’s unique numerical identifier
countrystringCountry code
statestringState where the store is located
citystringCity where the store is located
neighborhoodstringNeighborhood where the store is located
addressstringStreet where the store is located
numberstringStreet number of the store
complementstringComplementary information to the store’s address

Request body example:

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

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

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

Update store information

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:

AttributeTypeDescription
idstringStore DocumentId value, which represents the store ID number

Request body example (changing the mobileNumber):

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

Response body example:

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

Find a store

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.

ParamValue
data_entity_namestores
_schemav1

Delete a store

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

ParamValue
data_entity_namestores
idStore DocumentId value, which represents the store ID number

Sales associates


Create a sales associate

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

ParamValue
data_entity_namevendors
_schemav1

The request body should have the following properties:

AttributeTypeDescription
namestringSales associate name
userstringUser email
codestringSales associate code (optional)
storestringStore DocumentId value, which represents the store ID number

Request body example:

{
  "name": "Jane Doe",
  "user": "[email protected]",
  "code": "123456",
  "store": "16aa42c4-f489-11eb-82ac-0ea70a628d87"
}

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

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

Update sales associate information

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:

AttributeTypeDescription
idstringSales associate DocumentId value, which represents the sales associate ID number

Request body example:

{
  "id": "d74145dc-f494-11eb-82ac-1271e6f73475",
  "name": "Jane Doe",
  "user": "[email protected]",
  "code": "123456",
  "store": "16aa42c4-f489-11eb-82ac-0ea70a628d87",
}

Response body example:

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

Find a sales associate

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.

ParamValue
data_entity_namevendors
_schemav1

Delete a sales associate

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

ParamValue
data_entity_namevendors
idSales associate DocumentId value, which represents the sales associate ID number

Did this page help you?