---
title: "Read an event's guest list"
description: "Page who's coming to an event, who waits for your approval or a seat, filter and search it, see who canceled and why, and count it against the event's capacity."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read an event's guest list

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](/merchant-api/guides/approvals-and-waitlists)). This guide reads the list. It uses the `sherpo` helper from [your first call](/merchant-api/first-call) and a token with `customer:read`.

## Page the guest list

<a href="/merchant-api/reference/list-event-attendees/">`GET /products/{product}/attendees`</a> lists an event's attendees, latest registered first:

```bash
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"
```

```js
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:

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

- **`status`** is `going`, `pending` (their request waits for your approval, their seats held), `waitlisted` (they wait on the waitlist for a seat) or `canceled`. A canceled attendee's `cancel_reason` says why: `refunded`, `revoked` (you revoked their ticket), `expired` (a subscription or a dated ticket ran out), `declined` (you declined their request or waitlist place) or `canceled` (you [canceled the event](/merchant-api/guides/cancel-an-event)), and `canceled_at` says when. `registered_at` is 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.
- **`tier`** is the ticket type their access opens, else the one it last opened; `null` for a ticket with no tier. **`source`** says what gave the ticket that admits them (`checkout`, `payment`, `subscription`, `automation`, `manual` for a grant you give, in the app or through the API, or `api`; `waitlist` for a waitlist place no grant admits yet), **`grant_id`** names that grant, `null` while a request waits, and **`order_id`** names the order that paid for it, `null` for a grant no order paid (a `manual` grant with an order is a sale you recorded outside the store).
- **`answers`** are their answers to the event's [registration questions](/merchant-api/guides/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, and **`answered_by`** reads `buyer`; otherwise it reads `attendee`. 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](/merchant-api/guides/registration-questions#answer-for-a-customer).
- **`search`** matches the attendee's name, email or phone.
- **`bought_by`** is set on a guest someone else bought a ticket for: the buyer's `customer_id` and `customer`, and the `order_id`. **`guests`** counts the guests a buyer bought tickets for who still hold them.
- **Filters** take `customer_id`, `status`, `cancel_reason`, `tier_id`, `source`, `registered_at` and `bought_by` (a buyer's customer id, to read their group together).
- **Sorts** are `registered` (the default) and `canceled`, and `facets=status` or `facets=cancel_reason` counts the list by each.

The [product customers](/merchant-api/reference/list-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: <a href="/merchant-api/reference/record-refund/">`POST /orders/{order}/refunds`</a> 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

<a href="/merchant-api/reference/event-attendee-stats/">`GET /products/{product}/attendees/stats`</a> 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:

```bash
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees/stats' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/attendees/stats');
```

Answers `200`, abridged:

```json
{
  "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 <a href="/merchant-api/reference/get-product/">product read</a> and on its row of the <a href="/merchant-api/reference/list-products/">product list</a>, 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](/merchant-api/guides/cancel-an-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](/merchant-api/webhooks#events) 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.

Source: https://docs.sherpo.io/merchant-api/guides/event-guest-lists/index.mdx
