Developers
R2 Connect API

Customers

The business’s customer and guest directory with their visit and spending history.

GET/guestsrequires read:guests

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#

ParameterTypeDescription
limitintegerResults per page. Between 1 and 50. Default: 25.
cursorstringCursor for the next page.

Fields#

FieldTypeDescription
namestringCustomer name.
email · phonestringContact details. May be null if the business did not capture them.
countrystringCountry, when known.
statusstringcustomer if they already purchased, prospect if not yet.
visit_countintegerEffective stays or visits.
total_spentnumberAccumulated spending at the business.
segmentstringValue segment computed by R2.
no_show_countintegerTimes they did not show up for a reservation.
first_visit_at · last_visit_atdatetimeFirst 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#

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