Migrate your Klaviyo back in stock signups

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, which needs no code. Use this API route when the signups only exist as Klaviyo events.

Before you begin

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:

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.

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

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 in the developer docs, and Back in stock API for developers for how the API fits together.

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

Related guides