> ## 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.
# Back in stock
In Engage you can set up back-in-stock automations. These are used to notify customers when a particular product they have indicated an interest in is available to buy again.
The main steps of a back-in-stock flow in Engage are:
* Create a back-in-stock subscription
* Receive a stock level update
* Start the back-in-stock automation
* Send a back-in-stock email
This article will focus on the back-in-stock and stock-levels API endpoints.
## Back-in-stock API endpoints
In order to receive back-in-stock notifications, a contact needs to have a back-in-stock subscription registered in Engage. This subscription connects an Engage contact to a specific item (by the SKU).
Any back-in-stock subscription created will be deleted as soon as it has triggered a back-in-stock automation for that contact. The subscription is then seen as "used".
### 1 - Create a new subscription
A back-in-stock subscription is created using the following API endpoint:
```http theme={null}
POST /api/v3/inventory/backinstock/subscriptions
```
With the following kind of payload:
```json theme={null}
{
"contactId": "f5774867-8358-111f-85a4-af1200eced95",
"locale": "en-US",
"sku": "AD_0397_V_685_006_66",
"externalId": "12165253-34345"
}
```
The subscriber's Engage contact ID.
The SKU of the item being subscribed to.
Locale of the SKU and therefore which product feed to fetch product data from.
A reference to an entity in an external system, only required if the value is included in the stock level update.
A successful request gives a *HTTPS 201 Created* response.
Since the `contactId` is sent when creating a back-in-stock subscription, that contact needs to exist in Engage. If they don't exist, you'll need to create them. For example, when a user enters their email to request a back-in-stock message, and that email can't be connected to any existing contact.
When doing this, Voyado recommends using your default contact type and collecting the contact's consent for future communication. This will allow you to stay in touch after the back-in-stock notification has been sent, and communicate with that contact outside of the back-in-stock scope.
### 2 - Delete an existing subscription
A back-in-stock subscription is deleted like this:
```http theme={null}
DELETE /api/v3/inventory/backinstock/subscriptions/{subscriptionId}
```
The unique ID of the back-in-stock subscription.
A successful deletion gives a *HTTPS 204 No Content* response.
### 3 - Get all subscriptions for a contact
You can fetch all back-in-stock subscriptions for a contact like this:
```http theme={null}
GET /api/v3/contacts/{contactId}/backinstock/subscriptions
```
The standard GUID identifying a contact in Engage.
A successful request returns a *HTTPS 202 OK* response and this kind of data:
```json theme={null}
{
"data": [
{
"id": "cba5aba5-cf3c-40f5-a4db-b0d100bb2c7a",
"contactId": "48fba7e7-e447-4d90-a9ca-a86e00b1d8f4",
"sku": "AD_0743_V_395_001_31x65",
"locale": "en-US",
"externalId": "12165253-34345",
"createdOn": "2023-12-07T12:21:28+01:00"
},
{
"id": "bfca224c-de4c-4d61-903d-b0d100bb331c",
"contactId": "48fba7e7-e447-4d90-a9ca-a86e00b1d8f4",
"sku": "AD_0397_V_685_006_29",
"locale": "en-US",
"externalId": "12823253-89054",
"createdOn": "2023-12-07T12:21:34+01:00"
}
]
}
```
### 4 - Update one or several stock levels
This endpoint updates stock levels of one or more specific SKUs in Engage. This is then used to trigger the automations that will send back-in-stock communication to subscribed contacts.
Stock level updates are done like this:
```http theme={null}
PUT /api/v3/inventory/stock-levels
```
With this kind of payload:
```json theme={null}
[
{
"quantity": 15,
"locale": "sv-SE",
"sku": "AD_0397_V_685_006_29",
"externalId": "12165253-34345"
},
{
"quantity": 10,
"locale": "en-US",
"sku": "AD_0743_V_395_001_31x65",
"externalId": "48165253-23345"
}
]
```
For Engage to trigger a back-in-stock email, all products (including out of stock products) must be present in the product feed that is connected to Engage. If a product is not in the feed, a BIS email cannot be sent for it.
Latest stock quantity of the SKU.
The SKU of the item which has received a stock level change. This SKU has to exist in the product feed.
Locale of the SKU and therefore which product feed to fetch product data from.
Reference to an entity in external system.
A successful request gives a *HTTPS 202 Accepted* response.
Engage should be notified whenever the stock level of the given SKU has changed, or when it is considered back in stock. This enables Engage to keep track of the entire inventory regardless of the stock level. A stock quantity threshold of what the client considers to be "back in stock" can be configured in the automation trigger.
## locale and externalId in stock level updates
Although neither `locale` nor `externalId` are required for stock level updates, it's strongly recommended to include at least one of these attributes when a stock level update is done. Which one you use depends on what your subscription look like.
Consider the following situation. Five subscriptions are set up using these values (the `externalId` attribute is optional when setting up a subscription):
| Subscription | sku | locale | externalId |
| ------------ | ----- | ------ | ---------- |
| #1 | SKU-1 | sv-se | |
| #2 | SKU-1 | pl-pl | |
| #3 | SKU-1 | sv-se | SE-SKU-1 |
| #4 | SKU-1 | pl-pl | PL-SKU-1 |
| #5 | SKU-2 | sv-se | |
**Case 1:** The retailer sends `sku`, `quantity` and `locale` when doing a stock level update. An event is then triggered if both the `sku` and `locale` in the request match one or more of the subscriptions. The event created will be enriched based on the value in `locale`.
* Example: The retailer sends `sku` as "SKU-1" and locale as "sv-se", triggering subscriptions #1 and #3.
**Case 2:** The retailer sends `sku`, `quantity`, `externalId` in a stock update. Now for an event to be triggered, `sku` and `externalId` have to match a subscription. The event will be enriched based on `locale`.
* Example: The retailer sends `sku` as "SKU-1" and `externalId` as "SE-SKU-1", triggering subscription #3.
**Case 3:** The retailer sends only `sku` and `quantity` in a stock update. All subscriptions containing that `sku` will now be triggered regardless of their `externalId` or `locale` value. The event will be enriched based on the `locale`.
* Example: The retailer sends the `sku` as "SKU-1" which triggers subscriptions #1, #2, #3 and #4.
## Triggering the back-in-stock automation
For Engage to trigger a back-in-stock email, all products (including out of stock products) must be present in the product feed that is connected to Engage. If a product is *not* in the feed, a BIS (back-in-stock) email cannot be sent for it.
A stock level update sent to Engage triggers any back-in-stock automation triggers.
The following conditions must be met for a back-in-stock automation for a subscription to proceed.
1. The stock quantity must be higher than 0
2. A product feed must be configured for the specified locale
3. Product data must exist for the specified SKU
As well as these predefined conditions, you can also define custom conditions for your back-in-stock automation trigger based on:
* Locale
* Quantity
* SKU
* ExternalId
* Product data
* Subscription time
* Purchase
* Contact attributes
Once the automation has started (and passed all trigger conditions) that specific subscription will be deleted, regardless of whether the automation included communication to the subscriber or not.
A value split for `locale` is also supported in back-in-stock automations.
## Logging of back-in-stock
The integration log will show you which SKU has passed the predefined conditions in the automation, and the number of subscriptions that have been sent to the back-in-stock automation trigger.
