Skip to content

Read an event's guest list

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.

Updated

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
    }
  }
}
  • 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), 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, 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.
  • 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 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.

Type to search…

↑↓ navigate↵ selectEsc close