Every customer who has had a ticket to an event is on its guest list, once, however many tickets or renewals they hold: through a checkout, a subscription, an automation or a grant you give them. They stay going while a ticket holds, and they’re canceled once none does, with no call of yours. A guest whose request waits for your approval, or who waits on the event’s waitlist, is on it too (see Approve requests and run a waitlist). This guide reads the list. It uses the sherpo helper from your first call and a token with customer:read.
Page the guest list
GET /products/{product}/attendees lists an event’s attendees, latest registered first:
curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees?filter[status]=going&facets=status' \
-H "Authorization: Bearer $SHERPO_TOKEN"const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees', {
query: [
['filter[status]', 'going'],
['facets', 'status'],
],
});Answers 200, abridged:
{
"items": [
{
"id": "2f1e0d9c-8b7a-4695-8483-7261f5e4d3c2",
"product_id": "5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e",
"customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
"status": "going",
"cancel_reason": null,
"tier": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6a",
"name": "In person",
"rank": 2
},
"source": "checkout",
"grant_id": "4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807",
"order_id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
"registered_at": "2026-10-02T09:14:00.000Z",
"canceled_at": null,
"customer": {
"id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
"name": "Ada Lovelace",
"email": "ada@example.com",
"phone": null,
"erased": false
},
"answers": [
{
"question_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"value": "+39 333 123 4567"
}
],
"answered_by": "attendee",
"check_ins": [
{
"id": "4a5b6c7d-8e9f-4a0b-8c1d-2e3f4a5b6c7d",
"session_id": "8d7c6b5a-4f3e-4d2c-9b1a-0f9e8d7c6b5a",
"checked_in_at": "2026-11-07T18:04:00.000Z"
}
]
}
],
"cursor": null,
"facets": {
"status": {
"going": 1,
"canceled": 1
}
}
}statusisgoing,pending(their request waits for your approval, their seats held),waitlisted(they wait on the waitlist for a seat) orcanceled. A canceled attendee’scancel_reasonsays why:refunded,revoked(you revoked their ticket),expired(a subscription or a dated ticket ran out),declined(you declined their request or waitlist place) orcanceled(you canceled the event), andcanceled_atsays when.registered_atis when their current stretch of access began, so someone who comes back after a gap is registered again; renewals and upgrades without a gap keep the date.tieris the ticket type their access opens, else the one it last opened;nullfor a ticket with no tier.sourcesays what gave the ticket that admits them (checkout,payment,subscription,automation,manualfor a grant you give, in the app or through the API, orapi;waitlistfor a waitlist place no grant admits yet),grant_idnames that grant,nullwhile a request waits, andorder_idnames the order that paid for it,nullfor a grant no order paid (amanualgrant with an order is a sale you recorded outside the store).answersare their answers to the event’s registration questions, in the questions’ order. A guest someone else bought a ticket for, with no answers of their own, carries their buyer’s answers to the event, andanswered_byreadsbuyer; otherwise it readsattendee. The buyer answers once for every ticket they buy, so all their guests carry their latest answers. Anyone else who never went through checkout has none until you answer for them.searchmatches the attendee’s name, email or phone.bought_byis set on a guest someone else bought a ticket for: the buyer’scustomer_idandcustomer, and theorder_id.guestscounts the guests a buyer bought tickets for who still hold them.- Filters take
customer_id,status,cancel_reason,tier_id,source,registered_atandbought_by(a buyer’s customer id, to read their group together). - Sorts are
registered(the default) andcanceled, andfacets=statusorfacets=cancel_reasoncounts the list by each.
The product customers list answers the same people one row per grant or subscription, with their billing. The guest list keeps one row per person, so it’s the list to check people in from.
Group tickets
A customer who buys several tickets to an event names a guest for each one past their own, or for every one when they aren’t going. Each guest gets a ticket of their own: their own grant (source is checkout), their own row on the guest list and a ticket email that signs them in to your store with that address, as a new customer when you didn’t know them. The buyer can hand a ticket to someone else until its guest opens it and before the event starts; the old guest’s row is then canceled as revoked.
To refund one guest’s ticket, name it in the refund: POST /orders/{order}/refunds takes guests (the ids in the order line’s guests) on each of its allocations. Each guest named loses their ticket, is canceled as refunded and gives their seat back, whatever the store does with access on refunds. A refund of the whole payment that removes access ends every ticket it paid for and gives all of its seats back. A partial refund made at the processor names no guests, so it ends no ticket and frees no seat; one that refunds the whole payment ends its tickets and gives their seats back like a whole refund recorded here.
Count it against capacity
GET /products/{product}/attendees/stats counts who’s going, who’s pending and waitlisted, who canceled by reason, who’s going per tier (highest first), and the spots the event’s capacity leaves:
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees/stats' \
-H "Authorization: Bearer $SHERPO_TOKEN"const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees/stats');Answers 200, abridged:
{
"going": 42,
"pending": 4,
"waitlisted": 6,
"canceled": 3,
"canceled_by_reason": {
"refunded": 2,
"revoked": 1,
"expired": 0,
"declined": 0
},
"going_by_tier": [
{
"tier": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6a",
"name": "In person",
"rank": 2
},
"going": 30
},
{
"tier": null,
"going": 12
}
],
"checked_in_by_session": [
{
"session_id": "8d7c6b5a-4f3e-4d2c-9b1a-0f9e8d7c6b5a",
"checked_in": 38
}
],
"capacity": 50,
"remaining": 8,
"held_by_requests": 0,
"subscriptions": 0
}remaining is the seats left to sell, counted as checkout counts them: what open carts hold and sales took, so a ticket you grant takes none. A ticket type’s own capacity holds it too, so an event with no capacity of its own still has remaining once at least one ticket type is on sale and every one on sale is capped. It matches seats.spots_left on the product read and on its row of the product list, and never goes below zero; it’s null otherwise. A stored capacity no write could make reads as capacity: null and remaining: 0, holding the event full. held_by_requests is how many of the seats taken are held by requests still waiting for your approval, which go back on sale if you decline them. subscriptions counts the subscriptions to the event still running.
Both answer conflict on category for a product that isn’t an event.
What attendees hear
Each attendee is emailed when they’re registered on an event with a session ahead, with their ticket’s code as a QR code and a calendar file (a ticket from before the event had a session ahead gets its code in each update email instead, until a registration email reaches them), and again when a session ahead moves, changes place, is added or taken off, or the event’s location changes, a few minutes after the last edit, or once the event has no session ahead left. When you cancel the event, its event.canceled email tells each attendee what they get back, and a buyer who holds none of the tickets they bought gets event.purchase_canceled instead. Your webhook endpoints can take the same event.registered, event.updated and event.canceled events, one per attendee going, each with the attendee as this list reads them. Reminders a day and an hour before each session, and a thanks after the last one, reach the attendees as browser notifications.