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.
To read more about automations and email, go to the Engage Help Center.
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 / SKU. Any subscription created will be deleted as soon as it has triggered a back-in-stock automation for that contact.
1 - Create a new subscription
A back-in-stock subscription is created using the following API endpoint:
POST /api/v3/inventory/backinstock/subscriptions
With the following payload:
{
"ContactId": "f5774867-8358-445f-85a4-af1200eced95",
"Locale": "en-US",
"Sku": "AD_0397_V_685_006_29",
"ExternalId": "12165253-34345"
}Field | Type | Required | Description |
|---|---|---|---|
ContactId | Int | Yes | The subscriber's Engage Contact ID. |
Locale | String | Yes | Locale of the SKU and therefore which product feed to fetch product data from. |
Sku | String | Yes | The SKU of the item being subscribed to. |
ExternalId | String | No | A reference to an entity in external system, required if included in stock level update. |
A successful request gives a HTTPS 201 Created response.
Caution
Since the contactId is sent when creating a back-in-stock subscription, that contact needs to exist in Engage. If they don't, you'll need to create them. When doing this, we recommend using your default contact type and collecting consent for future communication. This will allow you to stay in touch after the back-in-stock notification has been sent, and also communicate with that contact outside of the back-in-stock scope.
Learn more about creating contacts and contact types in the contacts section.
2 - Delete an existing subscription
A back-in-stock subscription is deleted like this:
DELETE /api/v3/inventory/backinstock/subscriptions/{subscriptionId}
Field | Type | Required | Description |
|---|---|---|---|
subscriptionId | Int | Yes | 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:
GET /api/v3/contacts/{contactId}/backinstock/subscriptions
Field | Type | Required | Description |
|---|---|---|---|
contactId | GUID | Yes | The standard GUID identifying a contact in Engage. |
A successful request returns a HTTPS 202 OK response and this kind of data:
{
"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 - Creating the contact (if needed)
Since the contactId has to be sent when getting and creating subscriptions, a contact has to therefore exist in Engage. However, if a user enters their email to request a back-in-stock message, and that email can't be connected to any existing contact, then a contact has to be created.
When creating a contact in Engage, it is recommended that you use your default contact type and also collect consent for future communication to that user. This will ensure that you can maintain contact after the notification has been sent and communicate outside of the back-in-stock scope.
You can read more about creating contacts and contact types in the linked sections.
5 - 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:
PUT /api/v3/inventory/stock-levels
With this kind of payload:
[
{
"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"
}
]Caution
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.
Field | Type | Required | Description |
|---|---|---|---|
Quantity | Int | Yes | Latest stock quantity of the SKU. |
Locale | String | No | Locale of the SKU and therefore which product feed to fetch product data from. |
Sku | String | Yes | The SKU of the item which has received a stock level change. This SKU has to exist in the product feed. |
ExternalId | String | No | Reference to an entity in external system. |
A successful request gives a HTTPS 202 Accepted response.
Caution
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.
Using 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 (ExternalId 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
Caution
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.
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.
The stock quantity must be higher than 0
A product feed must be configured for the specified locale
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
Important
Once the automation workflow 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
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.
