Skip to content

Look up a customer's status

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

GET/customers/status

Costs 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

  • emailstringRequired

    The customer's email address, matched exactly but case-insensitively.

  • include_checkout_textboolean

    Also fetch the shipping text each preorder item showed at checkout from Shopify, which makes the call slower.

    Default false

Returns

  • emailstring
    Example: string
  • preordersarray of objects
    Show 12 child attributesHide child attributes
    • order_attribution_idstring
      Example: string
    • order_namestring
      Example: string
    • pathstring
      Example: string
    • placed_atstring
      Example: 2026-01-15T09:30:00Z
    • total_pricestring
      Example: string
    • currencystring
      Example: string
    • fulfillment_statusstring
      Example: string
    • preorder_fulfillment_statusnull
    • itemsarray of anys
    • other_items_countnull
    • paymentobject
      Show 8 child attributesHide child attributes
      • payment_statusstring
        Example: string
      • amount_paidnumber
        Example: 1.5
      • amount_outstandingstring
        Example: string
      • balance_due_amountnull
      • balance_due_atstring
        Example: 2026-01-15T09:30:00Z
      • balance_overdueboolean
        Example: true
      • balance_collectionnull
      • last_payment_attemptnull
    • created_atstring
      Example: 2026-01-15T09:30:00Z
  • more_preorders_countinteger
    Example: 1
  • back_in_stock_signupsarray of objects
    Show 6 child attributesHide child attributes
    • productnull
    • variantnull
    • channelstring
      Example: string
    • signed_up_atstring
      Example: 2026-01-15T09:30:00Z
    • notified_atnull
    • statusstring
      Example: string
  • more_signups_countinteger
    Example: 1

Errors

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The 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.

GET/customers/status
curl "https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "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
}