---
title: "Look up a customer's status"
description: "One customer's preorder and back-in-stock status by exact email — built for helpdesk sidebar widgets."
url: https://docs.stoqapp.com/v2-reference/customers-status/look-up-a-customers-status/
api: "API v2 reference"
method: GET
path: "/customers/status"
---

# Look up a customer's status

`GET https://app.stoqapp.com/api/v2/external/customers/status`

One customer's preorder and back-in-stock status by exact email: built for helpdesk sidebar widgets.

**Note:** `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.

## Query parameters

- `email` (string, required): The customer's email address, matched exactly but case-insensitively.
- `include_checkout_text` (boolean): Also fetch the shipping text each preorder item showed at checkout from Shopify, which makes the call slower.

## Returns

- `email` (string): e.g. `string`
- `preorders` (array of objects)
  - `order_attribution_id` (string): e.g. `string`
  - `order_name` (string): e.g. `string`
  - `path` (string): e.g. `string`
  - `placed_at` (string): e.g. `2026-01-15T09:30:00Z`
  - `total_price` (string): e.g. `string`
  - `currency` (string): e.g. `string`
  - `fulfillment_status` (string): e.g. `string`
  - `preorder_fulfillment_status` (null)
  - `items` (array of anys)
  - `other_items_count` (null)
  - `payment` (object)
    - `payment_status` (string): e.g. `string`
    - `amount_paid` (number): e.g. `1.5`
    - `amount_outstanding` (string): e.g. `string`
    - `balance_due_amount` (null)
    - `balance_due_at` (string): e.g. `2026-01-15T09:30:00Z`
    - `balance_overdue` (boolean): e.g. `true`
    - `balance_collection` (null)
    - `last_payment_attempt` (null)
  - `created_at` (string): e.g. `2026-01-15T09:30:00Z`
- `more_preorders_count` (integer): e.g. `1`
- `back_in_stock_signups` (array of objects)
  - `product` (null)
  - `variant` (null)
  - `channel` (string): e.g. `string`
  - `signed_up_at` (string): e.g. `2026-01-15T09:30:00Z`
  - `notified_at` (null)
  - `status` (string): e.g. `string`
- `more_signups_count` (integer): e.g. `1`

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Examples

### Look up a customer's status

```sh
curl "https://app.stoqapp.com/api/v2/external/customers/status?email=shopper%40example.com" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

### Look up a customer's status filtered by include_checkout_text

```sh
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"
```

## 200

Success: the requested resource.

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

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

