List and filter intents

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

GET/external/intents

Costs 1 rate-limit point · Rate limits

List back-in-stock intents (signups) for the shop, newest first. Supports filtering by Shopify product or variant, customer email or phone, creation date range, and notification status, with page-based pagination (up to 500 per page). Returns the matching intents alongside pagination metadata.

Query parameters

shopify_variant_idinteger
Filter by Shopify Variant ID
shopify_product_idinteger
Filter by Shopify Product ID
emailstring
Filter by customer email
phonestring
Filter by customer phone
start_datestring
Filter by start date (YYYY-MM-DD)
end_datestring
Filter by end date (YYYY-MM-DD)
notifiedboolean
Filter by notification status (true = notified, false = not notified)
pageinteger
Page number for pagination
per_pageinteger
Number of items per page (maximum 500)

Headers

X-Auth-TokenstringRequired
API key for authentication

Returns

intentsarray of objects
Show 27 child attributesHide child attributes
- idstring
  Unique identifier for the intent
- blocked_atstring, nullable
  Timestamp when the intent was blocked from sending
- channelstring
  Communication channel used for notifications (e.g., Email, SMS)
- emailstring
  Customer's email address for notifications
- notified_atstring, nullable
  Timestamp of the notification sent
- optin_confirmedboolean
  Whether the customer has confirmed their GDPR opt-in for notifications
- phonestring
  Customer's phone number for SMS notifications
- quantityinteger
  Requested quantity of the product when back in stock
- sent_notifications_countinteger
  Number of notifications sent for this intent
- sourcestring
  Example: api
- typestring
  Type of the intent (e.g., restock, wishlist_reminder)
- unsubscribed_atstring, nullable
  Timestamp when the customer unsubscribed from notifications
- created_atstring
  Timestamp when the intent was created
- updated_atstring
  Timestamp when the intent was last updated
- customer_idstring
  Unique identifier for the customer
- intent_trigger_idstring, nullable
  Identifier for the trigger that created this intent
- product_variant_idstring, nullable
  Internal product variant identifier
- shop_idstring
  Unique identifier for the shop
- shopify_inventory_item_idinteger, nullable
  Shopify's inventory item identifier
- shopify_market_idinteger, nullable
  Shopify's market identifier for multi-market stores
- shopify_product_idinteger, nullable
  Shopify's product identifier
- shopify_variant_idinteger, nullable
  Shopify's variant identifier
- customer_namestring, nullable
  Customer's full name
- contactstring, nullable
  Customer's contact information
- customer_unsubscribed_atstring, nullable
  Timestamp when the customer unsubscribed from all notifications
- accepts_marketingboolean, nullable
  Whether the customer has opted in to receive marketing communications
- notifications_countinteger, nullable
  Total number of notifications sent for this intent
metaobject
Show 4 child attributesHide child attributes
- total_countinteger
  Example: 128
- pageinteger
  Example: 1
- per_pageinteger
  Example: 25
- total_pagesinteger
  Example: 6

Errors

400

Bad request

401

Unauthorized

GET/external/intents

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

const res = await fetch("https://app.stoqapp.com/api/v1/external/intents", {
  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",
    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")
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)

Response

{
  "intents": [
    {
      "id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70",
      "channel": "email",
      "email": "shopper@example.com",
      "phone": null,
      "quantity": 1,
      "notified_at": null,
      "optin_confirmed": true,
      "source": "api",
      "type": "restock",
      "sent_notifications_count": 0,
      "created_at": "2026-06-20T14:30:00Z",
      "updated_at": "2026-06-20T14:30:00Z",
      "customer_id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "shop_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
      "shopify_product_id": 7891234567890,
      "shopify_variant_id": 43900910010503,
      "accepts_marketing": true
    }
  ],
  "meta": {
    "total_count": 128,
    "page": 1,
    "per_page": 25,
    "total_pages": 6
  }
}