Set up back in stock via API

If you want to include Klaviyo's back in stock functionality in your application or custom platform, you can accomplish this by calling the Create Back in Stock Subscription or Create Client Back in Stock Subscription 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 or text messages are notified.

📘
These API endpoints are valid for Shopify integrations, BigCommerce integrations, Magento 2 integrations, Square integrations, Wix integrations, accounts using our Catalogs API, or accounts with inventory-aware custom catalog feeds (custom catalogs that contain values for the $inventory_quantity and $inventory_policy fields).

We have an endpoint that can be used from server-side contexts as well as one that can be called directly from the client, e.g., a browser. Whether you are using our Catalog APIs or one of our supported e-commerce integrations, you can use these endpoints to subscribe your shoppers to receive notifications when catalog variants are back in stock.

Keep in mind that these endpoints will only be used to enqueue a profile to receive back in stock notifications.

We do not require explicit consent to be recorded in order to send email back in stock notifications. If you want to ensure that an email will be sent even if a shopper has previously unsubscribed from marketing, we recommend you also subscribe the profile to a list using Create Client Subscription on the client and Subscribe Profiles on the server. For SMS, you must always obtain explicit consent using Create Client Subscription on the client and Subscribe Profiles on the server to be able to send the text notifications. To learn more about how consent works in Klaviyo, please review our guide to collecting email and SMS consent.

Inputs

profile
The profile.
channels
The preferred channels through which the shopper wants to receive back in stock notifications.
relationships.variant
The catalog variant the shopper wants to receive. The id on this variant is a composite ID. The format of the id is: integrationType:::catalogId:::externalId, e.g. $magento_two:::MAGENTO_TWO_WEBSITE_ID-MAGENTO_TWO_STORE_ID:::MAGENTO_TWO_VARIANT_ID or $shopify:::$default:::SHOPIFY_VARIANT_ID.
1. integrationType
  One of $custom, $shopify, $bigcommerce, $magento_two, $square, or $wix.
2. catalogId
  Most catalog types in Klaviyo only support a single catalog. For all single-catalog integrations, use $default. For $magento_two, use your website ID followed by a "-" followed by your store ID, e.g. 1-1. Review this document for more details on retrieving these values.
3. externalId:
  The ID of the catalog variant in your external system.

Server-side request

Revision and authorization headers are required for all server-side requests, per the API Overview.

Email example

To send subscription information to the server-side API, send a POST request to https://a.klaviyo.com/api/back-in-stock-subscriptions. The endpoint description can be found here: Create Back in Stock Subscription.

Example:

{
  "data": {
    "type": "back-in-stock-subscription",
    "attributes": {
      "profile": {
        "data": {
            "type": "profile",
            "attributes": {
                "email": "[email protected]"
            }
        }
      },
      "channels": ["EMAIL"],
    },
    "relationships": {
      "variant": {
        "data": {
          "type": "catalog-variant",
          "id": "$shopify:::$default:::INSERT_SHOPIFY_CATALOG_VARIANT_ID"
        }
      }
    }
  }
}

If you also want to subscribe the profile to a list, send a separate POST request to the Subscribe Profiles endpoint.

SMS example

To send subscription information to the server-side API, send a POST request to https://a.klaviyo.com/api/back-in-stock-subscriptions/.

Example:

{
  "data": {
    "type": "back-in-stock-subscription",
    "attributes": {
      "profile": {
        "data": {
            "type": "profile",
            "attributes": {
                "phone_number": "+15005550006",
            }
        }
      },
      "channels": ["SMS"],
    },
    "relationships": {
      "variant": {
        "data": {
          "type": "catalog-variant",
          "id": "$magento_two:::2-2:::INSERT_MAGENTO_TWO_CATALOG_VARIANT_ID"
        }
      }
    }
  }
}

You’ll also want to obtain SMS consent for this profile so that they can receive the notification. Send an additional request to Subscribe Profiles.

{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "phone_number": "+15005550006"
              "subscriptions": {
                "sms": ["MARKETING"]
              }
          }
        ]
      }
    },
    "relationships": {
      "list": {
        "data": {"type": "list", "id": "Y6nRLr"}
    }
 }
}

Client-side request

Email example

To send subscription information to the client-side API, send a POST request to https://a.klaviyo.com/client/back-in-stock-subscriptions/?company_id=PUBLIC_API_KEY. The endpoint description can be found here: Create Client Back in Stock Subscription.

The example payload is the same as the server-side payload. Here’s an example of how you could use fetch to send this request:

const payload = {
  "data": {
    "type": "back-in-stock-subscription",
    "attributes": {
      "profile": {
        "data": {
            "type": "profile",
            "attributes": {
                "email": "[email protected]",
            }
        }
      },
      "channels": ["EMAIL"],
    },
    "relationships": {
      "variant": {
        "data": {
          "type": "catalog-variant",
          "id": "$shopify:::$default:::INSERT_SHOPIFY_CATALOG_VARIANT_ID"
        }
      }
    }
  }
}

var requestOptions = {
    method: 'POST',
    headers: {"Content-Type": "application/json"},
    body: payload,
};

fetch("https://a.klaviyo.com/client/back-in-stock-subscriptions/",requestOptions)
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));

SMS example

To send subscription information to the client-side API, use a POST request to https://a.klaviyo.com/client/back-in-stock-subscriptions/.

Example:

const payload = {
  "data": {
    "type": "back-in-stock-subscription",
    "attributes": {
      "profile": {
        "data": {
            "type": "profile",
            "attributes": {
                "phone_number": "+15005550006",
            }
        }
      },
      "channels": ["SMS"],
    },
    "relationships": {
      "variant": {
        "data": {
          "type": "catalog-variant",
          "id": "$magento_two:::2-2:::INSERT_MAGENTO_TWO_CATALOG_VARIANT_ID"
        }
      }
    }
  }
}

var requestOptions = {
    method: 'POST',
    headers: {"Content-Type": "application/json"},
    body: payload,
};

fetch("https://a.klaviyo.com/client/back-in-stock-subscriptions/",requestOptions)
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));

You’ll also want to obtain SMS consent for this profile so that they can receive the notification. Send an additional request to the Create Client Subscription endpoint.

const payload = {
  "data": {
    "type": "subscription",
    "attributes": {
      "list_id": "Y6nRLr",
      "custom_source": "Back in Stock",
      "phone_number": "+15005550006",
    }
  }
}

var requestOptions = {
    method: 'POST',
    headers: {"Content-Type": "application/json"},
    body: payload,
};

fetch("https://a.klaviyo.com/client/back-in-stock-subscriptions/",requestOptions)
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));

API responses

Success

When your request is accepted via our API, you’ll receive a 202 with no response body.

Error cases

Invalid email address or phone number:

{
    "errors": [
        {
            "id": "0dbfce59-0d68-442d-98c5-5b834b01e28c",
            "status": 400,
            "code": "invalid",
            "title": "Invalid input.",
            "detail": "Invalid email address",
            "source": {
                "pointer": "/data/attributes/email"
            },
            "meta": {}
        }
    ]
}

{
    "errors": [
        {
            "id": "ad5299f0-0ada-4158-a7bb-10a086895c50",
            "status": 400,
            "code": "invalid",
            "title": "Invalid input.",
            "detail": "Invalid phone number format (Example of a valid format: +12345678901)",
            "source": {
                "pointer": "/data/attributes/phone_number"
            },
            "meta": {}
        }
    ]
}

Invalid auth, client endpoint:

{
    "errors": [
        {
            "id": "c7d1ff60-bd2f-4189-be9e-9393e26b9f01",
            "status": 400,
            "code": "invalid",
            "title": "Invalid input.",
            "detail": "Invalid company ID TESTER",
            "source": {
                "pointer": "/data"
            },
            "meta": {}
        }
    ]
}

Invalid auth, server endpoint:

{
    "errors": [
        {
            "id": "64a2bdf8-5b28-4f05-9435-cb7cd423e2b1",
            "status": 401,
            "code": "not_authenticated",
            "title": "Authentication credentials were not provided.",
            "detail": "Missing or invalid private key.",
            "source": {
                "pointer": "/data/"
            }
        }
    ]
}

Invalid variant ID: If an invalid variant ID is included in a request, the API will return an error response. No event will be created for the profile and the customer will not be queued to receive a back in stock message.

{
    "errors": [
        {
            "id": "32227605-a762-4a9a-9787-c989c1fec07d",
            "status": 404,
            "code": "variant_not_found",
            "title": "The variant in your relationship payload does not exist",
            "detail": "The variant in your relationship payload does not exist",
            "source": {
                "pointer": "/data/relationships/variant/data/id"
            },
            "meta": {}
        }
    ]
}

Duplicate subscriptions

It is not possible to submit multiple events for a profile for the same variant. If multiple requests are submitted for the same profile 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.

After an individual receives a notification 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.

📘

Inputs

Server-side request

Email example

SMS example

Client-side request

Email example

SMS example

API responses

Success

Error cases

Duplicate subscriptions

🚧

Additional resources