Skip to main content

Back in stock

Warning

Back in stock is currently in closed beta and any part could change before the full release. Contact your account manager at Voyado if you want to try it out.

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/v2/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/v2/inventory/backinstock/subscriptions/{id}

Field

Type

Required

Description

id

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/v2/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"
        }
    ]
}

Stock levels endpoints

These two endpoints are used to fetch stock levels of a specific SKU to determine if it is back in stock. This is then used to trigger the automations that will send back-in-stock communication to subscribed contacts.

1 - Update a stock level

A stock level update is done like this:

PUT /api/v2/inventory/stock-levels

{
  "Quantity": 10,
  "Locale": "en-US",
  "Sku": "AD_0743_V_395_001_31x65"
  "ExternalId": "12165253-34345"
}

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 SKUhas 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.

2 - Update multiple stock levels

Several stock levels can be updated in a single request like this:

PUT /api/v2/inventory/stock-levels/batch

[
    {
        "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"  
    }
]

A successful request gives a HTTPS 202 Accepted response.

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

A stock level update sent to Engage triggers any "Back in stock" automation triggers.

backinstockautomations.png

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

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.

back-in-stock-01.png