Enable back in stock for custom catalog feeds

Before getting started

If you’ve already set up a custom catalog feed in Klaviyo, continue with the steps below to enable back in stock. Note that some of the steps needed to enable back in stock are in the configuration stage; they are outlined under ‘Optional fields’ in the custom catalog setup guide, and reiterated below in this article.

Feed setup

When you set up your custom catalog feed, make sure to include the following field for each item in your feed:

Inventory ($inventory_quantity): a number representing the stock available for a given item.

You can also include the following optional parameter:

Inventory Policy ($inventory_policy): a number that controls how we treat product visibility in product feeds/blocks. This field has two options:
- If the policy is set to 1, a product will not appear in dynamic product recommendation feeds and blocks if it is out of stock.
- If the policy is set to 2, a product can appear in dynamic product recommendation feeds and blocks regardless of inventory quantity. This is also the default behavior when this field is not set.

During the field mapping step, these fields should have the feed item fields: inventory_quantity and inventory_policy mapped to the Klaviyo fields $inventory_quantity and $inventory_policy respectively, and the field type should be Number.

Account settings and flow triggering

Once you've setup your feed and a Subscribed to Back in Stock event has been captured, the Back in Stock Settings will appear under Account > Settings > Email in your account. If you don't see these settings, make sure to trigger an event first. You can use these settings to determine how you would like to trigger back in stock flows.

To set up a back in stock alert flow, take a look at our How to build a back in stock flow guide.

Subscribing customers to back in stock alerts

When a customer subscribes to an alert when an item returns in stock, send a request to our back in stock endpoint. There are server-side and front-end versions of this request. For more information on which you should use, check out our custom integration FAQ.

Server-side request

To send subscription information to the server-side API, use a POST request. The information is sent to the server via the data JSON object, and serialized as a URL-encoded form. The JSON object requires all of the following arguments:

a - your public API key
email - the email address of the person subscribing to alerts for this item
variant - the ID of the item (must correspond with $id in the field mapping step)
platform - this should be set to “api”

curl -X POST \ https://a.klaviyo.com/api/v1/catalog/subscribe \
  -F a=abc123 \
  -F [email protected] \
  -F variant=64814-0004 \
  -F platform=api

Front-end request

A back in stock subscription request can also be sent using JavaScript. To do this, include the following parameters as an ajax request.

a - your public API key
email - the email address of the person subscribing to alerts for this item
variant - the ID of the item (must correspond with $id in the field mapping step)
platform - this should be set to “api”

$.ajax({
     type: "POST",
     url: "https://a.klaviyo.com/onsite/components/back-in-stock/subscribe",
     data: {
          a: "abc123",
          email: "[email protected]",
          variant: "64814-0004",
          platform: "api"
     },
     success: function(response){
          console.log(response) }
    })

API responses

Successful back in stock subscription

{"email": "[email protected]", "success": true}

Invalid email address or API key

{"errors": ["There was something wrong with your request. Please try again."], "data": {}, "success": false}

Missing form data parameters

{"status": 400, "message": "There was something wrong with your request: * email * This field is required."}

Invalid variants & duplicate subscriptions

The API does not validate variant IDs. If an invalid variant ID for an item is included in a request, the API will return a standard success response. No event will be created for this profile, and the customer will not be queued to receive a back in stock message.
It is not possible to submit multiple subscriptions for a profile on the same item variant. If multiple requests are submitted for the same email address on the same variant, only the first will be accepted.
- There is no limit to the number of unique item variants a profile can subscribe to.
- After an individual receives an email notifying them that a specific variant is back in stock, their existing subscription is cleared. They are then able to sign up for another subscription on that same variant.