HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
These docs are for v2023-02-22. Click to read the latest docs for v2024-10-15.

Set up back in stock via API

Learn how to set up Klaviyo's back in stock functionality via API.

🚧

Back in stock uses Klaviyo's v1/v2 legacy APIs.

New back in stock endpoints are coming in the future, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and new API overview.

If you want to include Klaviyo's back in stock functionality in your application or custom platform, you can accomplish this by calling the Subscribe endpoint from your app. You have full control of (and responsibility for) when, where, and how the trigger button appears; the appearance, text, and behavior of the modal; and all other aspects of the feature's behavior and appearance within your application.

Once you are successfully sending back in stock events to Klaviyo, you can set up a back in stock flow to ensure that profiles who subscribe to receive back in stock emails are notified.

📘

This API endpoint is only valid for Shopify integrations, BigCommerce integrations, Magento 2 integrations, or accounts with inventory-aware custom catalog feeds (custom catalogs that contain values for the $inventory_quantity and $inventory_policy fields).

Your POST request must include four inputs, with an optional fifth argument for Magento 2 implementations.

  1. a - Your public API Key, also known as the account ID.
  2. email - The email address entered by the subscriber, correctly formatted and valid.
  3. variant - The product's variant ID.
  4. platform - The platform ID, such as shopify, bigcommerce, magento_two, or api.
  5. store* - The numeric store ID. *Only required for Magento 2. Check out how to set up back in stock for Magento 2 for more information.

To subscribe a customer to a list as part of the back in stock workflow, you will need to make a separate, additional call to the List API.

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:

  1. a - Your public API Key.
  2. email - The email address entered by the subscriber, correctly formatted and valid.
  3. variant - The product's variant ID.
  4. platform - The platform ID, such as shopify, bigcommerce, magento_two, or api.
  5. store* - The numeric store ID. *Only required for Magento 2. Check out how to set up back in stock for Magento 2 for more information.
curl -X POST 'https://a.klaviyo.com/onsite/components/back-in-stock/subscribe' \
  -F a="ACCOUNT_ID" \
  -F email="EMAIL" \
  -F variant="VARIANT_ID" \
  -F platform="PLATFORM" \
  -F store="STORE_NUMBER"

Front-end request

A back in stock subscription request can be sent from a browser using JavaScript. To do this, include the following parameters:

  1. a - Your public API Key.
  2. email - The email address entered by the subscriber, correctly formatted and valid.
  3. variant - The product's variant ID.
  4. platform - The platform ID, such as shopify, bigcommerce, magento_two, or api.
  5. store* - The numeric store ID. *Only required for Magento 2. Check out how to set up back in stock for Magento 2 for more information.
var urlencoded = new URLSearchParams(),
    data = {
        "a":"ACCOUNT_ID",
        "email":"EMAIL",
        "variant":VARIANT_ID,
        "product":PRODUCT_ID,
        "platform":"PLATFORM"
    };
for (key in data) {
    urlencoded.append(key, data[key]);
}
var requestOptions = {
    method: 'POST',
    headers: {"Content-Type": "application/x-www-form-urlencoded"},
    body: urlencoded,
    redirect: 'follow'
};


fetch("https://a.klaviyo.com/onsite/components/back-in-stock/subscribe", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
JavaScript
$.ajax({
     type: "POST",
     url: "https://a.klaviyo.com/onsite/components/back-in-stock/subscribe",
     data: {
          a: "ACCOUNT_ID",
          email: "EMAIL",
          variant: "VARIANT_ID",
          platform: "PLATFORM",
          store: "STORE_NUMBER"
     },
     success: function(response){
          console.log(response) }
    })

API responses

Success

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

Invalid email address

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

Invalid public 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 variant ID

The API does not validate variant IDs. If an invalid variant ID is included in a request, the API will return a standard success response. No event will be created for the profile and the customer will not be queued to receive a back in stock message.

Duplicate subscriptions

It is not possible to submit multiple events for a profile on the same 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 variants that a profile can subscribe to. A single person can sign up to be notified for hundreds or thousands of unique variants.

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. 

🚧

Subscribers will not be notified when an item is restocked if you do not first set up a back in stock flow! Check out the resources below to get started.

Additional resources