> Documentation index: https://docs.sellhidden.com/llms.txt

# Customers

Source: https://docs.sellhidden.com/reference/customers

Everyone who checked out or signed in on your storefront, with lifetime aggregates.

## Endpoints

5 endpoints · [customers:read](https://docs.sellhidden.com/start?scope=customers%3Aread#scopes) · [customers:write](https://docs.sellhidden.com/start?scope=customers%3Awrite#scopes)

Base URL https://api.sellhidden.com/v1 · Authorization: Bearer · 120/min per key · cursor pagination · Idempotency-Key on POST · No test mode

### GET /customers — List customers

Scope `customers:read`.

**Query parameters**

| Query parameters | Type | Description |
| --- | --- | --- |
| `email` | string | Email contains this text. |
| `hasAccount` | true \| false | Only buyers who signed in (or only guests). |
| `limit` | 1..100 | Page size. Default 50. |
| `cursor` | string | nextCursor from the previous page. |

```bash
curl https://api.sellhidden.com/v1/customers \
  -H "Authorization: Bearer hsk_live_…"
```

### GET /customers/{id} — Get a customer

With aggregates and the ten most recent orders. Scope `customers:read`.

```bash
curl https://api.sellhidden.com/v1/customers/ID \
  -H "Authorization: Bearer hsk_live_…"
```

Response (200):

```json
{
  "ok": true,
  "customer": {
    "id": "clx…",
    "email": "buyer@example.com",
    "name": null,
    "hasAccount": true,
    "balanceUsd": 12.5,
    "lastLoginAt": "2026-09-25T18:20:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z",
    "orderCount": 4,
    "topUpCount": 1,
    "totalSpentUsd": 116,
    "openTicketCount": 0,
    "recentOrders": [ { "id": "clx…", "status": "delivered", … } ]
  }
}
```

### POST /customers/{id}/balance — Adjust store balance

Adds (positive) or removes (negative) store credit. The balance never goes below zero (409 balance_too_low). The reason is written to the audit log. Scope `customers:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `amountUsd` (required) | number | Positive to credit, negative to debit. |
| `reason` (required) | string | Up to 300 characters. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/customers/ID/balance \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountUsd": 10,
    "reason": "Goodwill credit for the delayed delivery."
  }'
```

Response (200):

```json
{ "ok": true, "customer": { "id": "clx…", "email": "buyer@example.com", "balanceUsd": 10, … }, "change": { "amountUsd": 10, "reason": "…" } }
```

### POST /customers/{id}/ban — Ban a customer

Blocks the buyer's email at checkout (a blacklist rule you also see under Blacklist in the dashboard). Scope `customers:write`. Accepts `Idempotency-Key`. Returns 201.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `reason` | string | Private note, up to 300 characters. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/customers/ID/ban \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Chargeback."}'
```

Response (201):

```json
{ "ok": true, "customer": { "id": "clx…", "email": "buyer@example.com", "banned": true }, "ban": { "ruleId": "clx…", "reason": "Chargeback.", "createdAt": "…" }, "alreadyBanned": false }
```

### DELETE /customers/{id}/ban — Lift a ban

Scope `customers:write`.

```bash
curl -X DELETE \
  https://api.sellhidden.com/v1/customers/ID/ban \
  -H "Authorization: Bearer hsk_live_…"
```