Skip to main content

Stores API endpoints

There are the endpoints used for working with stores.

Get all stores

Use this endpoint to fetch all the stores for your tenant.

GET /api/v2/stores

Add includeInactive as "true" to include inactive stores in the response:

GET /api/v2/stores?includeInactive=true

The response will have this structure:

[
  {
    "name": "010",
    "city": null,
    "countryCode": null,
    "county": null,
    "email": null,
    "adjacentZipCodes": null,
    "emailUnsubscribeText": null,
    "emailViewOnlineText": null,
    "externalId": "010",
    "footerHtml": null,
    "headerHtml": null,
    "homepage": null,
    "phoneNumber": null,
    "region": null,
    "senderAddress": null,
    "senderName": null,
    "street": null,
    "type": "RETAIL",
    "zipCode": null,
    "active": true,
    "timeZone": null
  }
]

This example contains just one store object, but a real response will usually contain many.

Create a store

To create a store, use this endpoint with the following payload structure:

POST /api/v2/stores

{
  "name": "string",
  "city": "string",
  "countryCode": "string",
  "county": "string",
  "email": "string",
  "adjacentZipCodes": "string",
  "emailUnsubscribeText": "string",
  "emailViewOnlineText": "string",
  "externalId": "string",
  "footerHtml": "string",
  "headerHtml": "string",
  "homepage": "string",
  "phoneNumber": "string",
  "region": "string",
  "senderAddress": "string",
  "senderName": "string",
  "street": "string",
  "type": "string",
  "zipCode": "string",
  "active": "boolean",
  "timeZone": "string",
  "locale": "string"
}

The required fields here are name and externalId. The POST request will return a 400 error if these are missing from the payload.

And while it's not required by the API, you should also specify timeZone since the Engage UI requires it and you'll probably be accessing the store through the UI at some point.

Voyado also recommends that you include the type (either "ecom" or "retail") as well as country. This contributes to good reporting and segmentation.

Important

To reduce the possibility of error you should always include these when creating a store over the API:

  • name

  • externalId

  • timeZone

  • type

  • country

Get a single store

You can fetch a single store's data if your know its external ID:

GET /api/v2/stores/{externalId}

Update a single store

You can also update a store with a POST to the same endpoint:

POST /api/v2/stores/{externalId}

The payload will be similar to the one you used to create the store:

{
  "name": "string",
  "city": "string",
  "countryCode": "string",
  "county": "string",
  "email": "string",
  "adjacentZipCodes": "string",
  "emailUnsubscribeText": "string",
  "emailViewOnlineText": "string",
  "externalId": "string",
  "footerHtml": "string",
  "headerHtml": "string",
  "homepage": "string",
  "phoneNumber": "string",
  "region": "string",
  "senderAddress": "string",
  "senderName": "string",
  "street": "string",
  "type": "string",
  "zipCode": "string",
  "active": "boolean",
  "timeZone": "string",
  "locale": "string"
}

Caution

Only send the values you want to change, which means a smaller payload than the one shown above. Any empty or null values sent in the payload will overwrite the existing values for that store.

The payload you will usually send to update a store looks more like this:

{
  "homepage": "newhomepage.com"
}