Reference

API v1 (legacy)

API v1 is the older API. It still works, but new integrations should use API v2. Migrating from v1 to v2

Back in Stock

Before diving into the API reference, it's important to understand the key term we use - Intent

Intents are essentially "waitlist requests" or "subscriptions" that customers create when they want to be notified with a back in stock alert.

Core Purpose:
- When a product is out of stock, customers can sign up to be notified when it becomes available again
- Each intent represents a single customer's request to be notified about a specific product variant.
- Intent is unique to a customer, product variant & market.
What data is present in an Intent?
- Customer Information: Each intent contains customer details like email, phone, and name
- Product Information: Shopify product and product variant IDs
- Notification Preference: Specifies how the customer wants to be notified (email or SMS)
- Quantity: How many units the customer is interested in when the product is back in stock
Lifecycle of an Intent:
- Created when a customer signs up for notifications
- Can be notified when the product becomes available
- Can be blocked from sending notifications
- Can be unsubscribed by the customer
- Tracks notification history and opt-in status
Compliance & Privacy:
- Includes GDPR opt-in confirmation tracking
- Tracks marketing preferences
- Maintains unsubscribe status

Preorders

Before diving into the API reference, it's important to understand the key term we use - Selling Plans

What are Selling Plans?

Selling Plans in the context of preorders are configurations that define how a preorder product is sold, billed, and delivered to customers.

Core Purpose:

Enable merchants to sell products before they're in stock or available for immediate shipping
Define payment schedules, delivery timelines, and inventory management for preordered items
Provide customization options for how preorders appear and function in the storefront

What data is present in a Selling Plan?

Basic Information: Name, internal reference name, enabled status
Billing Configuration: When and how much to charge (at checkout or later), charge types (percentage or fixed amount)
Delivery Settings: When products will be delivered (exact date or interval after purchase)
Inventory Management: How inventory is reserved and which system manages it
Pricing Options: Discount amounts or percentages for preordered items
UI Customization: Button text, badge styling, shipping information text

Variant Association:

Selling plans can be associated with product variants in three ways:
- All products in the store
- Products in a specific collection
- Custom selection of individual variants
Each variant can have custom settings like shipping text and maximum preorder quantity

Multi-Market Support:

Selling plans can be configured for specific markets in multi-market stores
Different markets may have different preorder terms or availability

Base URL

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

Authentication

Send the store's API key in the X-Auth-Token header on every request. How to get a key

Rate limits

A read costs 1 point and a write 2. Rate limits and errors

Resources

Back in Stock8 endpoints Preorders11 endpoints

Your first request

curl "https://app.stoqapp.com/api/v1/external/intents/products_in_demand" \
  -H "X-Auth-Token: $STOQ_API_KEY"

const res = await fetch("https://app.stoqapp.com/api/v1/external/intents/products_in_demand", {
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
  },
});
const data = await res.json();

import os
import requests

res = requests.get(
    "https://app.stoqapp.com/api/v1/external/intents/products_in_demand",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v1/external/intents/products_in_demand")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)