Look up a customer's status
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/customers/statusCosts 1 rate-limit point · Rate limits
One customer's preorder and back-in-stock status by exact email: built for helpdesk sidebar widgets.
email is matched exactly, ignoring case and surrounding spaces; an unknown email returns 200 with empty lists. Shows up to 3 preorders, unfulfilled first, then newest (cancelled and refunded orders are left out, fulfilled ones after 30 days), and the 3 newest signups; more_preorders_count and more_signups_count count the rest, looking at the 25 newest orders at most. include_checkout_text=true makes one Shopify call to fill told_at_checkout, scheduled_for and other_items_count, which are null without it.
Also searched ascustomer statusgorgias sidebarcustomer preorder statuscustomer back in stock status
Query parameters
emailstringRequiredThe customer's email address, matched exactly but case-insensitively.
include_checkout_textbooleanAlso fetch the shipping text each preorder item showed at checkout from Shopify, which makes the call slower.
Defaultfalse
Returns
emailstringExample:stringpreordersarray of objectsShow 12 child attributesHide child attributes
order_attribution_idstringExample:stringorder_namestringExample:stringpathstringExample:stringplaced_atstringExample:2026-01-15T09:30:00Ztotal_pricestringExample:stringcurrencystringExample:stringfulfillment_statusstringExample:stringpreorder_fulfillment_statusnullitemsarray of anysother_items_countnullpaymentobjectShow 8 child attributesHide child attributes
payment_statusstringExample:stringamount_paidnumberExample:1.5amount_outstandingstringExample:stringbalance_due_amountnullbalance_due_atstringExample:2026-01-15T09:30:00Zbalance_overduebooleanExample:truebalance_collectionnulllast_payment_attemptnull
created_atstringExample:2026-01-15T09:30:00Z
more_preorders_countintegerExample:1back_in_stock_signupsarray of objectsShow 6 child attributesHide child attributes
productnullvariantnullchannelstringExample:stringsigned_up_atstringExample:2026-01-15T09:30:00Znotified_atnullstatusstringExample:string
more_signups_countintegerExample:1
Errors
invalid_paramsOne or more fields failed the action's schema.
validation_failedThe request failed validation.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl "https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com", {
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/v2/external/customers/status?email=shopper%40example.com",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com")
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)curl "https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com&include_checkout_text=false" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com&include_checkout_text=false", {
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/v2/external/customers/status?email=shopper%40example.com&include_checkout_text=false",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com&include_checkout_text=false")
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){
"email": "string",
"preorders": [
{
"order_attribution_id": "string",
"order_name": "string",
"path": "string",
"placed_at": "2026-01-15T09:30:00Z",
"total_price": "string",
"currency": "string",
"fulfillment_status": "string",
"preorder_fulfillment_status": null,
"items": [
null
],
"other_items_count": null,
"payment": {
"payment_status": "string",
"amount_paid": 1.5,
"amount_outstanding": "string",
"balance_due_amount": null,
"balance_due_at": "2026-01-15T09:30:00Z",
"balance_overdue": true,
"balance_collection": null,
"last_payment_attempt": null
},
"created_at": "2026-01-15T09:30:00Z"
}
],
"more_preorders_count": 1,
"back_in_stock_signups": [
{
"product": null,
"variant": null,
"channel": "string",
"signed_up_at": "2026-01-15T09:30:00Z",
"notified_at": null,
"status": "string"
}
],
"more_signups_count": 1
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}