STOQ Back in Stock API - Complete Guide

The Back in Stock API lets you manage customer waitlist requests (called "Intents") programmatically. Perfect for custom integrations, headless setups, or automating notification workflows. This article provides a high-level overview of our Back in Stock API capabilities. For complete documentation, detailed parameters, request/response examples, and interactive testing, visit docs.stoqapp.com/back-in-stock-api

Base URL: https://app.stoqapp.com/api/v1/

Authentication: API Key (get it from: Back in stock alerts > Integrations in your STOQ dashboard)

What are Intents?

Intents are customer requests to be notified when an out-of-stock product becomes available again. Think of them as waitlist signups.

Each Intent includes:

• Customer info (email, phone, name)
• Product details (variant ID, product ID)
• Notification preference (email or SMS)
• Quantity they want
• Status (pending, sent, or blocked)

Getting Your API Key

To use the Back in Stock API, you'll need your API key:

1. Open STOQ app inside your Shopify Admin
2. Go to "Back in stock alerts > Integrations"
3. Scroll down to find "API Key" section
4. Click copy to get your API key
5. Important: Keep your API key secure and never share it publicly.

Key API Capabilities

1. Create Intents

This API lets you add customers to the waitlist for a product programmatically. Great for building custom experiences on your storefront, integrating with headless commerce setups, or capturing interest from unconventional touchpoints like social media campaigns or email flows.

Use Case: Integrate STOQ into custom themes, headless storefronts, or checkout flows.

Endpoint: POST /api/v1/intents.json

Headers

{
  "X-Shopify-Shop-Domain": "your-store.myshopify.com",
  "Content-Type": "application/json"
}

Body Parameters

{
  "intent": { // The Product Variant the customer intends to buy
    "shopify_variant_id": 111111111, // The ID for the Shopify Variant
    "shopify_product_id": 222222222, // The ID for the Shopify Product
    "shopify_market_id": 1, // Shopify market ID (use 1 if unsure)
    // The channel: "email" (requires customer.email) or "sms" (requires customer.phone)
    "channel": "email",
    "quantity": 2, // The quantity of the Variant they want
    "source": "api" // Don't change this
  },
  "customer": { // Customer details
    // Customer id from a previous API call (optional)
    // Sending id updates the same customer instead of creating a new one
    // "id": "1861e9da-13c8-4fdb-93d2-1ca5dc4ecbe8",
    "name": "John Doe", // Customer's name (optional but recommended)
    "email": "customer@example.com", // Required if channel is "email"
    "phone": "918123676393", // Required if channel is "sms" (no '+' prefix)
    "country_code": "91", // Country code (optional but recommended)
    "country": "in", // Two letter ISO code (optional, improves phone validation)
    "accepts_marketing": true, // Whether they accept marketing emails
    "locale": "en" // Customer locale (optional)
  },
  "product": { // Optional - only needed for optin confirmation or shop alerts
    "variant_count": 3, // The number of variants the Product has
    "title": "Cool T-Shirt", // The title for the Shopify Product
    "variant_title": "Blue / Large" // The title for the Shopify Variant
  }
}

Example 1: Basic Email Signup

fetch('https://app.stoqapp.com/api/v1/intents.json', {
  method: 'POST',
  headers: {
    'X-Shopify-Shop-Domain': 'your-store.myshopify.com',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    intent: {
      shopify_variant_id: 111111111,
      shopify_product_id: 222222222,
      shopify_market_id: 1,
      channel: 'email',
      quantity: 2,
      source: 'api'
    },
    customer: {
      name: 'John Doe',
      email: 'customer@example.com',
      phone: '918123676393',
      country_code: '91',
      country: 'in',
      accepts_marketing: true,
      locale: 'en'
    },
    product: {
      variant_count: 3,
      title: 'Cool T-Shirt',
      variant_title: 'Blue / Large'
    }
  })
})
.then(response => response.json())
.then(data => console.log('Success:', data))
.catch(error => console.error('Error:', error));

Example 2: SMS Channel

fetch('https://app.stoqapp.com/api/v1/intents.json', {
  method: 'POST',
  headers: {
    'X-Shopify-Shop-Domain': 'your-store.myshopify.com',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    intent: {
      shopify_variant_id: 333333333,
      shopify_product_id: 444444444,
      shopify_market_id: 1,
      channel: 'sms',
      quantity: 1,
      source: 'api'
    },
    customer: {
      name: 'Jane Smith',
      phone: '12025550123',
      country_code: '1',
      country: 'us',
      accepts_marketing: false,
      locale: 'en'
    },
    product: {
      variant_count: 2,
      title: 'Cool Hat',
      variant_title: 'Red'
    }
  })
})
.then(response => response.json())
.then(data => console.log('Success:', data))
.catch(error => console.error('Error:', error));

Example 3: Minimal Required Fields

fetch('https://app.stoqapp.com/api/v1/intents.json', {
  method: 'POST',
  headers: {
    'X-Shopify-Shop-Domain': 'your-store.myshopify.com',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    intent: {
      shopify_variant_id: 555555555,
      shopify_product_id: 666666666,
      shopify_market_id: 1,
      channel: 'email',
      quantity: 1,
      source: 'api'
    },
    customer: {
      email: 'minimal@example.com'
    }
  })
})
.then(response => response.json())
.then(data => console.log('Success:', data))
.catch(error => console.error('Error:', error));

📖 Full Documentation: docs.stoqapp.com/back-in-stock-api/create-an-intent

2. List & Filter Intents

Retrieve all your waitlist signups with powerful filtering options. Perfect for building custom dashboards, syncing data to your CRM, analyzing demand patterns, or exporting lists for marketing campaigns. You can filter by product, date range, notification channel, and signup status.

Use Case: Export waitlists, sync with CRM, or build custom dashboards.

Endpoint: GET /api/v1/external/intents?state=pending&shopify_variant_id=123456789

Available Filters:

• state - pending, sent, or blocked
• shopify_variant_id - specific variant
• channel - email or sms
• created_after / created_before - date range
• Pagination: page, per_page (max 100)

3. Notify Customers

Trigger back-in-stock notifications to your waiting customers when products become available. This is the heart of the API - use it to send alerts individually or in bulk. Ideal for integrating with your inventory management system, ERP, or warehouse software to automatically notify customers the moment stock arrives.

Use Case: Trigger notifications from your inventory management system when stock arrives.

Single Notification:

POST /api/v1/external/intents/{intent_id}/notify

Bulk Notifications:

POST /api/v1/external/intents/bulk_notify
Body: { "intent_ids": ["id1", "id2", "id3"] }

4. Transfer Signups

Seamlessly move waitlist signups from one product variant to another. This is a lifesaver when you're consolidating products, restructuring your catalog, discontinuing a variant, or migrating customers to a newer model. All customer preferences and data are preserved during the transfer.

Endpoint: POST /api/v1/external/intents/transfer_signups

Example:

{
  "from_shopify_variant_id": 123456789,
  "from_shopify_product_id": 555666777,
  "to_shopify_variant_id": 987654321,
  "to_shopify_product_id": 111222333,
  "intent_type": "pending"
}

Use Case: Consolidating variants, product restructuring, or migrating to new SKUs.

5. Delete Intents

Clean up your waitlist by removing pending signups. Useful for GDPR compliance, removing duplicate entries, or clearing out old signups that are no longer relevant. Note that you can only delete intents that haven't been notified yet - this protects your notification history.

Endpoint: DELETE /api/v1/external/intents/bulk_destroy

{ "intent_ids": ["id1", "id2"] }

Important: Cannot delete intents that have already been notified.

6. Products in Demand Report

Discover which products your customers want most. This powerful endpoint aggregates all your waitlist data to show you demand trends by variant. Use this intelligence to make smarter purchasing decisions, prioritize restocks, identify trending products, and forecast inventory needs. It's like having a crystal ball for your inventory planning.

Endpoint: GET /api/v1/external/intents/products_in_demand?sort_by=total&sort_order=desc

Returns:

• Total intents per variant
• Pending intents count
• Last requested date
• Product details

Filters:

• Date range: start_date, end_date
• Sorting: sort_by (total, pending, last_requested_at)
• Pagination

Use Case: Prioritize restocking decisions, identify trending products.

Quick Start Example

// 1. Get your API key from STOQ dashboard

// 2. List all pending waitlist signups for a variant
const response = await fetch(
  'https://app.stoqapp.com/api/v1/external/intents?shopify_variant_id=123456789&state=pending',
  {
    headers: {
      'X-Auth-Token': 'YOUR_API_KEY'
    }
  }
);

// 3. Notify all pending customers when stock arrives
const intents = await response.json();
const intentIds = intents.intents.map(i => i.id);

await fetch('https://app.stoqapp.com/api/v1/external/intents/bulk_notify', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ intent_ids: intentIds })
});

Testing the API

You can test any API endpoint using the "Test it" feature:

1. Go to https://docs.stoqapp.com
2. Select the API you wish to test and click on "Test it" button

3. Enter the API key and required data to see the result

Authentication

Header: X-Auth-Token: YOUR_API_KEY

Most endpoints require authentication using your API key. The exception is the Create Intent endpoint which uses the X-Shopify-Shop-Domain header instead.

Full API Reference

For detailed parameters, response schemas, and interactive API testing, visit:** docs.stoqapp.com/back-in-stock-api. **If you need any assistance in using the APIs, feel free to contact our 24/7 Live Support. We're happy to help!

Updated on: 14/01/2026