Back in stock

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"  
}

A successful request gives a HTTPS 201 Created response.

A back-in-stock subscription is deleted like this:

DELETE /api/v2/inventory/backinstock/subscriptions/{id}

A successful deletion gives a HTTPS 204 No Content response.

You can fetch all back-in-stock subscriptions for a contact like this:

GET /api/v2/contacts/{contactId}/backinstock/subscriptions

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

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.

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"
}

A successful request gives a HTTPS 202 Accepted response.

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.

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):

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.

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.

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.