API reference
Customers
Everyone who checked out or signed in on your storefront, with lifetime aggregates.
Endpoints
GET/customerscustomers:read
List customers.
| Query parameters | Type | Description |
|---|---|---|
| Type: string | Email contains this text. | |
| hasAccount | Type: true | false | Only buyers who signed in (or only guests). |
| limit | Type: 1..100 | Page size. Default 50. |
| cursor | Type: string | nextCursor from the previous page. |
curl https://api.sellhidden.com/v1/customers \
-H "Authorization: Bearer hsk_live_…"GET/customers/{id}customers:read
Get a customer. With aggregates and the ten most recent orders.
curl https://api.sellhidden.com/v1/customers/ID \
-H "Authorization: Bearer hsk_live_…"200 OKjson
{
"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}/balancecustomers:writeIdempotency-Key
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.
| Body | Type | Description |
|---|---|---|
| amountUsdrequired | Type: number | Positive to credit, negative to debit. |
| reasonrequired | Type: string | Up to 300 characters. |
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."
}'200 OKjson
{ "ok": true, "customer": { "id": "clx…", "email": "buyer@example.com", "balanceUsd": 10, … }, "change": { "amountUsd": 10, "reason": "…" } }POST/customers/{id}/bancustomers:writeIdempotency-Key201
Ban a customer. Blocks the buyer's email at checkout (a blacklist rule you also see under Blacklist in the dashboard).
| Body | Type | Description |
|---|---|---|
| reason | Type: string | Private note, up to 300 characters. |
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."}'201 Createdjson
{ "ok": true, "customer": { "id": "clx…", "email": "buyer@example.com", "banned": true }, "ban": { "ruleId": "clx…", "reason": "Chargeback.", "createdAt": "…" }, "alreadyBanned": false }DELETE/customers/{id}/bancustomers:write
Lift a ban.
curl -X DELETE \
https://api.sellhidden.com/v1/customers/ID/ban \
-H "Authorization: Bearer hsk_live_…"Get help
Send us the endpoint, the request or delivery id and the response you got. Security findings go through responsible disclosure. Live platform status is on the support page.
See also