Customers
The business’s customer and guest directory with their visit and spending history.
Off by default. This endpoint only responds for accounts where R2 has enabled the customer directory. Without it, it returns 403 guests_disabled even if the key has the read:guests permission. Once enabled, each key returns at most 5,000 customers per day; when the cap is reached it returns 429 daily_limit until the next day (UTC).
Ordered by most recent visit. Includes both customers with spending and prospects who have not purchased yet.
Parameters#
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Results per page. Between 1 and 50. Default: 25. |
| cursor | string | Cursor for the next page. |
Fields#
| Field | Type | Description |
|---|---|---|
| name | string | Customer name. |
| email · phone | string | Contact details. May be null if the business did not capture them. |
| country | string | Country, when known. |
| status | string | customer if they already purchased, prospect if not yet. |
| visit_count | integer | Effective stays or visits. |
| total_spent | number | Accumulated spending at the business. |
| segment | string | Value segment computed by R2. |
| no_show_count | integer | Times they did not show up for a reservation. |
| first_visit_at · last_visit_at | datetime | First and last visit. |
This is personal data
This resource returns personal information about real people. Handle it under the data protection law that applies to the business and to your company: store it encrypted, limit who can see it, and delete it when the commercial relationship ends or when the data subject requests it.
Example#
{
"data": [
{
"id": "u82jd7fk2msq04nb",
"name": "Gabriela Ortiz",
"email": "[email protected]",
"phone": "+525551234567",
"country": "MX",
"status": "customer",
"visit_count": 4,
"total_spent": 18400,
"segment": "loyal",
"no_show_count": 0,
"first_visit_at": "2025-11-02T18:30:00.000Z",
"last_visit_at": "2026-07-16T10:15:00.038Z"
}
],
"pagination": { "cursor": "g3QAAAACZAAE…", "has_more": true }
}