API · Guest list

Guest list admissions are complimentary named parties. They consume real ticket inventory, skip checkout, and are not customers. Use this API instead of a hidden 0€ promo code.

The JSON shape is pinned to the integration tests in Usetix. If a test fails with “API payload shape drifted”, update this page.

Writes with an API token (no signed-in user) are attributed to the account owner. Numbered seats are never auto-assigned: send event_place_ids from ticket_options.available_places. Group tickets, whole tables, and numbered-seat walk-ins are not available here. Scanner walk-ins stay a door action.

Related: orders (origin, delivery_email, staff_note), events (guest-list counts), and scanner tickets.

`GET /admin/events/:event_slug/guest_list`

Lists guest parties for an event, plus eligible ticket types and currently available inventory.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  "https://app.usetix.io/admin/events/spring-showcase/guest_list"

Query parameters:

Parameter	Description
`query`	Guest name, companion name, or delivery email.
`filter`	`all` (default), `expected`, or `arrived`.

Response:

{
  "query": "",
  "filter": "all",
  "expected_count": 2,
  "arrived_count": 0,
  "admission_count": 2,
  "ticket_options": [
    {
      "id": 12,
      "title": "General Admission",
      "inventory_kind": "ga",
      "available_stock": 48,
      "unlimited_stock": false,
      "standing_areas": [],
      "available_places": []
    }
  ],
  "guest_parties": [
    {
      "public_id": "gst_abc123",
      "order_code": "7K3Q9D2A",
      "display_number": "7K3Q-9D2A",
      "status": "paid",
      "origin": "guest_list",
      "customer_name": "Anna Müller",
      "delivery_email": null,
      "staff_note": "Use the side entrance",
      "arrival_state": "expected",
      "arrived_count": 0,
      "party_size": 2,
      "cancellable": true,
      "ticket_id": 12,
      "ticket_title": "General Admission",
      "creator_name": "Alex Organizer",
      "paid_at": "2026-08-22T10:15:00Z",
      "created_at": "2026-08-22T10:15:00Z",
      "admissions": [
        {
          "public_id": "itm_lead",
          "attendee_name": "Anna Müller",
          "place_label": null,
          "check_in_code": "9M5V2H8C",
          "display_check_in_code": "9M5V-2H8C",
          "redeemed": false,
          "redeemed_at": null,
          "admission_status": "active",
          "cancellable": true,
          "seat_exchangeable": false
        },
        {
          "public_id": "itm_plus_one",
          "attendee_name": "Guest of Anna Müller",
          "place_label": null,
          "check_in_code": "4P8R1L6N",
          "display_check_in_code": "4P8R-1L6N",
          "redeemed": false,
          "redeemed_at": null,
          "admission_status": "active",
          "cancellable": true,
          "seat_exchangeable": false
        }
      ]
    }
  ]
}

inventory_kind is ga, standing, or places. Unlimited stock returns "available_stock": null and "unlimited_stock": true. For standing tickets, standing_areas lists open pools. For numbered tickets, available_places lists currently free seats as { "id", "key", "label" }. key is the stable seat logical key (the same identifier MCP’s places action returns).

`GET /admin/events/:event_slug/guest_parties/:public_id`

Returns one guest party. HTML requests redirect to the edit screen.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties/gst_abc123

Response: 200 OK with the guest party JSON.

`POST /admin/events/:event_slug/guest_parties`

Creates a complimentary party and takes inventory immediately.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"guest_party": {"customer_name": "Anna Müller", "party_size": 2, "ticket_id": 12, "staff_note": "Use the side entrance"}}' \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties

Numbered seats:

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"guest_party": {"customer_name": "Anna Müller", "ticket_id": 15, "event_place_ids": [401, 402]}}' \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties

Body parameters (inside guest_party):

Field	Required	Notes
`customer_name`	yes	Door-search name.
`ticket_id`	yes	An eligible standard ticket from `ticket_options`.
`party_size`	no	1–20. Ignored when `event_place_ids` is present (size is the number of places). Defaults to 1.
`event_place_ids`	numbered tickets	IDs from `ticket_options.available_places`. Required for `places` tickets. Do not invent them.
`event_capacity_pool_id`	standing, if more than one area	From `ticket_options.standing_areas`. When the ticket has a single standing area, Usetix picks it.
`delivery_email`	no	Optional ticket delivery. Not the guest’s identity.
`send_to_creator`	no	If true, delivers to the acting organizer (API tokens: the account owner).
`staff_note`	no	Internal hint, max 500 characters. Scanner-only.

Response: 201 Created with the guest party JSON and a Location header. 422 Unprocessable Entity with { "errors": { "field": ["..."] } } when the name is blank, the ticket is ineligible, stock is gone, or the seats are no longer free.

`PATCH /admin/events/:event_slug/guest_parties/:public_id`

Updates names, delivery email, and staff note. Omitted fields stay as they are. Send deliver: true at the top level (not inside guest_party) to email tickets after saving.

curl -X PATCH \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"deliver": true, "guest_party": {"delivery_email": "guest@example.com", "staff_note": "Notify the event manager", "attendee_names": {"itm_plus_one": "Berta Meier"}}}' \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties/gst_abc123

attendee_names is a map of admission public_id → companion name. The lead name is customer_name. Empty delivery_email or staff_note clears the field.

Response: 200 OK with the updated party. 422 if deliver is true and there is still no delivery address.

`POST /admin/events/:event_slug/guest_parties/:public_id/cancellation`

Removes an untouched party and restores inventory. Fails once anyone in the party has checked in.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties/gst_abc123/cancellation

Response: 200 OK with the party (status is booking_cancelled). 422 if the party is no longer cancellable.

`POST /admin/events/:event_slug/guest_parties/:public_id/admissions/:admission_public_id/cancellation`

Releases one unredeemed admission. Standing parties split the remaining capacity instead of trapping it.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/events/spring-showcase/guest_parties/gst_abc123/admissions/itm_plus_one/cancellation

Response: 200 OK with the updated party. 422 if that admission cannot be released (already in, accessibility pair, and so on).

Seat moves

Numbered guest-list seats use the same seat-exchange endpoints as paid seated orders.

`GET /admin/order_items/:public_id/seat_exchange`

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/order_items/itm_lead/seat_exchange

{
  "public_id": "itm_lead",
  "place_label": "Ground floor · Stalls · A · 1",
  "current_place_id": 401,
  "available_places": [
    { "id": 402, "key": "seat-a-2", "label": "Ground floor · Stalls · A · 2" }
  ]
}

`POST /admin/order_items/:public_id/seat_exchange`

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"seat_exchange": {"event_place_id": 402}}' \
  https://app.usetix.io/admin/order_items/itm_lead/seat_exchange

{
  "public_id": "itm_lead",
  "place_label": "Ground floor · Stalls · A · 2",
  "previous_place_label": "Ground floor · Stalls · A · 1"
}

Linked wheelchair/companion places cannot be moved individually. Wallet passes update when installed. Email is sent only when the party has a delivery address.

Guest party fields

Field	Type	Notes
`public_id`	string	Stable party ID. Use it in URLs.
`order_code`	string	Human-readable order code.
`display_number`	string	Formatted code, typically `XXXX-XXXX`.
`status`	string	Usually `paid`. `booking_cancelled` after a whole-party cancel.
`origin`	string	Always `guest_list`.
`customer_name`	string	Lead name used at the door.
`delivery_email`	string \| null	Ticket delivery only. Null for door-list-only parties.
`staff_note`	string \| null	Internal scanner hint.
`arrival_state`	string	`expected`, `partially_arrived`, or `arrived`.
`arrived_count`	integer	Checked-in admissions.
`party_size`	integer	Active admissions remaining.
`cancellable`	boolean	Whole party can still be removed.
`ticket_id`	integer \| null	Ticket type of the admissions.
`ticket_title`	string \| null	Snapshot title.
`creator_name`	string \| null	Who added the party. API tokens use the account owner.
`paid_at`	string \| null	ISO 8601 UTC.
`created_at`	string	ISO 8601 UTC.
`admissions`	array	See below.

Admission fields

Field	Type	Notes
`public_id`	string	Use for companion updates, admission cancel, and seat exchange.
`attendee_name`	string	Display name at the door, including “Guest of …” when unnamed.
`place_label`	string \| null	Numbered or standing label, when assigned.
`check_in_code`	string	Human-readable ticket code.
`display_check_in_code`	string	Formatted code.
`redeemed`	boolean	Checked in.
`redeemed_at`	string \| null	ISO 8601 UTC.
`admission_status`	string	`active`, `cancelled`, or a refund-style status. Guest list does not take payment.
`cancellable`	boolean	This admission can be released.
`seat_exchangeable`	boolean	This numbered place can be moved.

AI and MCP

The same operations exist on manage_guest_list for the in-app assistant and MCP. Actions: list, tickets, places, add, update, cancel, cancel_admission, move_seat. Numbered add/move use place_keys (the key values above), not invented labels. See MCP.