List and filter intents

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

GET

/external/intents

const url = 'https://app.stoqapp.com/api/v1/external/intents';
const options = {method: 'GET', headers: {'X-Auth-Token': '<X-Auth-Token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://app.stoqapp.com/api/v1/external/intents \
  --header 'X-Auth-Token: <X-Auth-Token>'

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.

Authorizations

ApiKeyAuth

Parameters

Header Parameters

X-Auth-Token

required

string

API key for authentication

Query Parameters

shopify_variant_id

integer

Filter by Shopify Variant ID

shopify_product_id

integer

Filter by Shopify Product ID

email

string

Filter by customer email

phone

string

Filter by customer phone

start_date

string format: date

Filter by start date (YYYY-MM-DD)

end_date

string format: date

Filter by end date (YYYY-MM-DD)

notified

boolean

Filter by notification status (true = notified, false = not notified)

page

integer

Page number for pagination

per_page

integer

Number of items per page (maximum 500)

Responses

200

A paginated list of intents

application/json

object

intents

Array<object>

object

Unique identifier for the intent

string

blocked_at

Timestamp when the intent was blocked from sending

string format: date-time

nullable

channel

Communication channel used for notifications (e.g., Email, SMS)

string

email

Customer’s email address for notifications

string

notified_at

Timestamp of the notification sent

string format: date-time

nullable

optin_confirmed

Whether the customer has confirmed their GDPR opt-in for notifications

boolean

phone

Customer’s phone number for SMS notifications

string

quantity

Requested quantity of the product when back in stock

integer

sent_notifications_count

Number of notifications sent for this intent

integer

source

string

type

Type of the intent (e.g., restock, wishlist_reminder)

string

unsubscribed_at

Timestamp when the customer unsubscribed from notifications

string format: date-time

nullable

created_at

Timestamp when the intent was created

string format: date-time

updated_at

Timestamp when the intent was last updated

string format: date-time

customer_id

Unique identifier for the customer

string

intent_trigger_id

Identifier for the trigger that created this intent

string

nullable

product_variant_id

Internal product variant identifier

string

nullable

shop_id

Unique identifier for the shop

string

shopify_inventory_item_id

Shopify’s inventory item identifier

integer

nullable

shopify_market_id

Shopify’s market identifier for multi-market stores

integer

nullable

shopify_product_id

Shopify’s product identifier

integer

nullable

shopify_variant_id

Shopify’s variant identifier

integer

nullable

customer_name

Customer’s full name

string

nullable

contact

Customer’s contact information

string

nullable

customer_unsubscribed_at

Timestamp when the customer unsubscribed from all notifications

string format: date-time

nullable

accepts_marketing

Whether the customer has opted in to receive marketing communications

boolean

nullable

notifications_count

Total number of notifications sent for this intent

integer

nullable

meta

object

total_count

integer

page

integer

per_page

integer

total_pages

integer

Example

{
  "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
  }
}

400

Bad request

401

Unauthorized

Was this page helpful?

Still stuck? Ask Quinn or chat with support