> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stores
All your stores, whether physical or digital, are represented in the Engage database. They are either added manually by you, or created automatically whenever a purchase references a store that does not yet exist in your Engage environment.
## Stores and contacts
Every contact in Engage has two stores connected to them:
**Created-in store**: Also known as the recruited-in store, this is the store where a contact was first added to Engage. Once this is added to a contact's data it cannot ever be changed.
**Regular store**: This is the contact's "usual" store as determined by RFM values. This can change based on the contact's behaviour.
When a contact is created, the regular store is by default the created-in / recruited-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:
In Engage, go to **Administration**, then select **Stores** and **Stores** again.
On the **Stores** page select "Create store" in the upper right corner.
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.
Ensure the "Active" checkbox is checked and then select "Save".
## Changing 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 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.
Your Voyado team needs to make adjustments to the Engage back-end. Contact them for this step.
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.
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.
### Create a store
To create a store, use this endpoint with the following payload structure:
```http theme={null}
POST /api/v3/stores
```
```json Payload structure theme={null}
{
"name": "string",
"externalId": "string",
"type": "string",
"timeZone": "string",
"city": "string",
"county": "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 here are `name` and `externalId`. The POST request will return a *400* error if these are missing from the payload.
While 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
* `type`: Given as either "ECOMM" or "RETAIL" or "OTHER"
* `countryCode`: For example "SE", "FI", "IR" - Used to improve reporting and segmentation
The string value for the country will be calculated from the `countryCode` value so you don't need to send that. Note that `county` also exists as an attribute. This can be seen as an area that's between `city` and `region` in size.
### Get all stores
Use this endpoint to fetch all your stores.
```http theme={null}
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:
```json theme={null}
[
{
"name": "010",
"externalId": "010",
"city": null,
"countryCode": null,
"county": null,
"email": null,
"adjacentZipCodes": null,
"emailUnsubscribeText": null,
"emailViewOnlineText": null,
"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.
### Get a single store
You can fetch a single store's data if your know its external ID:
```http theme={null}
GET /api/v3/stores/{externalId}
```
### Update a single store
You can update a store using the same endpoint:
```http theme={null}
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:
```http theme={null}
{
"homepage": "newhomepage.com"
}
```