Stores

Every contact in Engage has two stores connected to them:

• Created-in store: Where a contact was first added to Engage. Once added can’t be changed.
• Regular store: A contact’s “usual” store determined by RFM values. This can change.

When a contact is created, the regular store is by default the created-in store.

Working with stores

Your active stores should be set up in Engage before contacts are created. Additionally, any new stores that open should also be added. This allows customers to be linked to the correct recruited-in store or regular store through the store ID in their purchase data.

If a transaction is processed by Engage using a store ID that doesn’t exist, then Engage will create that store.

Creating a store

Here is how to create a store in Engage:

1. Navigate to the stores section in Engage

   In Engage, go to Administration, then select Stores and Stores again.

2. Create a new store

   On the Stores page select “Create store” in the upper right corner.

3. Fill in store details

   Fill in the fields. Required fields are “Store”, “Time zone” and “External ID”.

   The “Store” field is the display name for this store as it will be shown in Engage. It should be unique to reduce confusion but doesn’t have to be.

   The “External ID” is the one on the receipt. It is usually found in your ERP system. This is the store’s unique ID in Engage and can’t be the same as another store in Engage.

   
4. Save and create

   Ensure the “Active” checkbox is checked and then select “Save”.

Changing a store’s External ID

A store’s External ID is used to connect imported receipts with that store. If you change a store’s External ID in Engage, but are still sending receipts using the old External ID, Engage will then create a new store using that old External ID. That is not good.

To correctly change a store’s External ID, the customer needs to stop sending receipts using the old External ID, then change the External ID value in Engage, and then begin sending receipts using the store’s new External ID. Doing it this way avoids any issues.

Be sure, if changing a store’s External ID, that you do it the way described above.

Sending email as a specific store

When designing an e-mail send-out, there’s a way to decide which product feed will be used to populate it. To get this working, there’s a few things to do in the Engage back-end and front-end.

1. Configuration in Engage

   Your Voyado team needs to make adjustments to the Engage back-end. Contact them for this step.

2. Edit the store

   When that’s done, go to the Engage frontend and select Administation then Stores and then Stores again. You’ll see a list of all your stores. Selecting one takes you to Edit store. Scroll down to the Spare fields section. Locate the “Locale” field.

   This is where you will enter the same locale as the one specified in whatever product feed you want to use for this store.

   
3. Do the sendout

   Now, when you are creating an email, you can select “Send as a specific store” and select the store (and, indirectly,the locale or product feed connected to it) that will be used for this send-out.

   

If you define the “locale” attribute for all stores, even physical, you can send as any store using the correct language/currency when creating a email send-out. You are not restricted to just e-com stores.

It’s only possible to get data from ONE specific product feed for every email send-out. Therefore, in Engage, you can only use one language (and one currency) per send-out.

API endpoints for stores

Here are the endpoints used for working with stores.

Get all stores

Use this endpoint to fetch all your stores.

GET /api/v3/stores?includeInactive=true

Optionally add includeInactive as “true” as shown above to include inactive stores in the response. Leave it out if you don’t need it (the default is “false”).

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/v3/stores

Payload structure

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

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

While it’s not required, 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. The fields type (either “ecom” or “retail”) as well as country (“SE”, “FI”, etc) are also recommendeded to improve reporting and segmentation.

Get a single store

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

GET /api/v3/stores/{externalId}

Update a single store

You can update a store using the same endpoint:

POST /api/v3/stores/{externalId}

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

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

The payload you’ll usually send to update a store looks more like this, containing only the value or values to change:

{
  "homepage": "newhomepage.com"
}