Create customer intent to buy product

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

POST/intents.json

Costs 2 rate-limit points · Rate limits

Create a new intent for a customer to be notified when a product is back in stock. Unlike other API endpoints for Back in Stock, this API endpoint does not require an API Key.

Headers

X-Shopify-Shop-DomainstringRequired
The Shopify shop domain (e.g. 'restock-rocket-demo.myshopify.com')
Content-TypestringRequired
Must be application/json
One of application/json

Request body

intentobjectRequired
Show 6 child attributesHide child attributes
- shopify_variant_idintegerRequired
  The ID for the Shopify Variant
- shopify_product_idintegerRequired
  The ID for the Shopify Product
- shopify_market_idinteger
  The ID for the Shopify Market (for multi-market stores)
- channelstringRequired
  The notification channel (email requires customer.email, sms requires customer.phone)
  One of emailsms
- quantityintegerRequired
  The quantity of the Variant they want
- sourcestringRequired
  Should be set to 'api'
  One of api
customerobjectRequired
Show 10 child attributesHide child attributes
- idstring
  Optional customer id from previous API call response
- namestring
  Customer's name (Shop must be on standard plan or above)
- emailstring
  Customer email address (required if channel is email)
- phonestring
  Customer phone number with country code but without '+' (required if channel is sms)
- country_codestring
  Country code for the customer phone number
- countrystring
  Country in two letter code for the customer (improves phone number validation)
- accepts_marketingboolean
  Whether the customer has agreed to receive email content from your online store
- localestring
  Customer locale
- shopify_market_idinteger
  Customer's Shopify Market ID for multi-market stores
- shopify_customer_idstring
  Customer's Shopify ID
productobject
Product data is only needed if you have optin confirmation or alerts to your shop set up
Show 5 child attributesHide child attributes
- variant_countinteger
  The number of variants the Shopify Product has
- titlestring
  The title for the Shopify Product
- variant_titlestring
  The title for the Shopify Variant
- vendorstring
  The vendor/brand of the product
- skustring
  The SKU of the variant

Returns

errorsarray of strings

Errors

400

Bad request

401

Unauthorized

POST/intents.json

curl -X POST "https://app.stoqapp.com/api/v1/intents.json" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": {
      "shopify_variant_id": 43900910010503,
      "shopify_product_id": 7891234567890,
      "channel": "email",
      "quantity": 1,
      "source": "api"
    },
    "customer": {
      "email": "shopper@example.com",
      "name": "Alex Shopper",
      "accepts_marketing": true,
      "country": "us"
    }
  }'

const res = await fetch("https://app.stoqapp.com/api/v1/intents.json", {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "intent": {
      "shopify_variant_id": 43900910010503,
      "shopify_product_id": 7891234567890,
      "channel": "email",
      "quantity": 1,
      "source": "api"
    },
    "customer": {
      "email": "shopper@example.com",
      "name": "Alex Shopper",
      "accepts_marketing": true,
      "country": "us"
    }
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://app.stoqapp.com/api/v1/intents.json",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
    json={
        "intent": {
            "shopify_variant_id": 43900910010503,
            "shopify_product_id": 7891234567890,
            "channel": "email",
            "quantity": 1,
            "source": "api"
        },
        "customer": {
            "email": "shopper@example.com",
            "name": "Alex Shopper",
            "accepts_marketing": True,
            "country": "us"
        }
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v1/intents.json")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
  intent: {
    shopify_variant_id: 43900910010503,
    shopify_product_id: 7891234567890,
    channel: "email",
    quantity: 1,
    source: "api"
  },
  customer: {
    email: "shopper@example.com",
    name: "Alex Shopper",
    accepts_marketing: true,
    country: "us"
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

{
  "errors": [
    "string"
  ]
}

{
  "intents": [
    {
      "channel": "email",
      "email": "shopper@example.com",
      "phone": null,
      "quantity": 1,
      "source": "api",
      "type": "restock",
      "optin_confirmed": false,
      "notified_at": null,
      "shopify_product_id": 7891234567890,
      "shopify_variant_id": 43900910010503,
      "shopify_market_id": null,
      "country": null,
      "created_at": "2026-06-20T14:30:00Z",
      "customer": {
        "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
      }
    }
  ],
  "errors": []
}