---
title: "Migrate your Klaviyo back in stock signups"
description: "Move an existing Klaviyo back in stock waitlist into STOQ with a one-time API migration, so you don't lose people who are still waiting."
url: https://help.stoqapp.com/back-in-stock/migrate-klaviyo-back-in-stock-signups/
product: "Back in Stock"
section: "Integrations / Move from another app"
last_updated: 2026-11-01
---

# Migrate your Klaviyo back in stock signups

> Move an existing Klaviyo back in stock waitlist into STOQ with a one-time API migration, so you don't lose people who are still waiting.

If you ran back in stock through Klaviyo before switching to STOQ, the customers who already signed up live in Klaviyo, not STOQ. This guide is a one-time migration: pull those signups out of Klaviyo and recreate them as STOQ waitlist entries (intents), so everyone still waiting gets notified from STOQ when the product restocks.

This is a developer task. If you can export your signups as a simple spreadsheet of email and variant instead, use [Import your waitlist](https://help.stoqapp.com/back-in-stock/import-waitlist/), which needs no code. Use this API route when the signups only exist as Klaviyo events.

## Before you begin

| Requirement | Detail |
|---|---|
| Comfort running a script | You call two REST APIs: read from Klaviyo, write to STOQ. Any language works; the reference approach below uses Node. |
| A Klaviyo private API key | With `metrics:read`, `events:read`, and `profiles:read` scopes. Create it in Klaviyo under **Settings > API keys**. |
| Your shop details | Your `.myshopify.com` domain, and your Shopify market ID if you use markets. |
| STOQ set up | STOQ installed and the Notify me widget live, so restocks trigger alerts. See [Set up back in stock alerts](https://help.stoqapp.com/back-in-stock/set-up-back-in-stock-alerts/). |

No STOQ API key is needed. The intents endpoint identifies your shop from the `X-Shopify-Shop-Domain` header, the same way the storefront widget creates signups.

## How the migration works

The migration reads Klaviyo's back in stock events and turns each into a STOQ intent:

1. **Find your Klaviyo back in stock metric**

   Klaviyo logs a metric event whenever someone subscribes, often named **Subscribed to Back in Stock**. Look up its metric ID through the Klaviyo API (or pass the exact name if yours differs).

2. **Pull the signup events**

   Page through the events for that metric. Each event gives you the customer's email (from the linked profile) and, from the event's properties, the product and variant they signed up for. The exact property names depend on how your old Klaviyo flow captured them, so the migration checks a few common spellings for the variant and product ID.

3. **Clean the list**

   Drop any signup missing an email or a variant ID, since STOQ needs both to know who to notify and about what. Then dedupe by email and variant, keeping the most recent signup.

4. **Skip items already back in stock**

   Check each variant's current stock and skip the ones already in stock. Those customers don't need a waitlist entry, and this keeps you from adding people for products that are already available.

5. **Create a STOQ intent for each signup**

   Send each remaining signup to STOQ's back in stock API as a new intent.

## Read the profiles from Klaviyo

Find your back in stock metric's ID, then page through that metric's events with `include=profile` so each event comes back with the customer's profile (their email) alongside the product they signed up for. Authenticate with your Klaviyo **private** API key.

```bash
# 1. Find the back in stock metric's ID (look for your event's name in the response)
curl -s -G "https://a.klaviyo.com/api/metrics/" \
  --data-urlencode 'fields[metric]=name' \
  -H "Authorization: Klaviyo-API-Key YOUR_PRIVATE_KEY" \
  -H "revision: 2024-10-15" \
  -H "accept: application/json"

# 2. Page through that metric's events, pulling each signup's profile (email)
curl -s -G "https://a.klaviyo.com/api/events/" \
  --data-urlencode 'filter=equals(metric_id,"YOUR_METRIC_ID")' \
  --data-urlencode 'include=profile' \
  --data-urlencode 'fields[event]=datetime,event_properties' \
  --data-urlencode 'fields[profile]=email' \
  --data-urlencode 'page[size]=200' \
  --data-urlencode 'sort=-datetime' \
  -H "Authorization: Klaviyo-API-Key YOUR_PRIVATE_KEY" \
  -H "revision: 2024-10-15" \
  -H "accept: application/json"
```

Each event's `event_properties` hold the product and variant IDs (the exact key names depend on how your original flow captured them), and the `included` profile gives the email. Follow the `links.next` cursor to page through every event. Your key needs the `metrics:read`, `events:read`, and `profiles:read` scopes. See Klaviyo's [Get Events](https://developers.klaviyo.com/en/reference/get_events) reference for the full response shape.

## Create an intent in STOQ

For each signup, send a `POST` to the intents endpoint. Authenticate with your shop domain header, no API key:

```bash
curl -X POST https://app.stoqapp.com/api/v1/intents.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com" \
  -d '{
    "intent": {
      "shopify_variant_id": 1234567890,
      "shopify_product_id": 9876543210,
      "shopify_market_id": 1,
      "channel": "email",
      "quantity": 1,
      "source": "api"
    },
    "customer": {
      "email": "customer@example.com",
      "accepts_marketing": true
    }
  }'
```

A successful call returns `201 Created`. For the full request and response schema, see [Create an intent](https://docs.stoqapp.com/v1/operations/intents-json-post/) in the developer docs, and [Back in stock API for developers](https://help.stoqapp.com/back-in-stock/back-in-stock-api/) for how the API fits together.

> **Tip**
>
> Run the migration in a dry-run mode first that does everything except the final POST, and write the results to a report file. Review the counts and a sample of rows, then run it for real. Migrate only out-of-stock signups so STOQ doesn't message people about products that are already available.

## Check your setup

After running the migration, open **Reports > Back in Stock > Current waitlist** in STOQ and confirm the migrated customers appear, linked to the right products. Spot-check a few against your Klaviyo list. From here on, when one of those products restocks, STOQ sends the alert.

## FAQ

### Will migrating re-send old back in stock emails to these customers?

No. Creating an intent adds the customer to the STOQ waitlist; it doesn't send anything on its own. The alert only goes out later, when the product actually restocks.

### Do I need a STOQ API key for this?

No. The intents endpoint authenticates with the `X-Shopify-Shop-Domain` header, the same as the storefront widget. You only need a Klaviyo key to read the events out of Klaviyo.

### What happens to signups missing a variant ID?

They're skipped. STOQ needs the variant to know which product to notify about. This usually means the original Klaviyo event didn't capture the variant, so those signups can't be migrated automatically.

### Should I migrate signups for products that are already back in stock?

No. Skip in-stock variants during the migration. Those customers no longer need a waitlist entry, and migrating them adds noise for products that are already available.

### Can I do this without code?

Only if you can get the signups as a spreadsheet of email and variant. If you can, use [Import your waitlist](https://help.stoqapp.com/back-in-stock/import-waitlist/) instead. Klaviyo back in stock signups usually live as events with the variant buried in event properties, which is why this API route exists.

## Related guides

- [Import your waitlist](https://help.stoqapp.com/back-in-stock/import-waitlist/): The no-code option when you can export email and variant as a CSV.
- [Back in stock API for developers](https://help.stoqapp.com/back-in-stock/back-in-stock-api/): The endpoints, keys, and rate limits behind the intents call.
- [Switch to STOQ from another back in stock app](https://help.stoqapp.com/back-in-stock/switch-to-stoq-for-back-in-stock/): The full checklist for moving your back in stock setup to STOQ.
- [Sync back in stock signups to Klaviyo](https://help.stoqapp.com/back-in-stock/connect-klaviyo-for-back-in-stock/): Keep sending through Klaviyo going forward, if you'd rather not fully switch.