Browse API docs

Seat map and holds

A hold keeps places of a seated event back from the shop under a name. What it is follows from what it carries:

  • with an email, a reservation for a person, who buys the places through their own link,
  • with a sales_point, an allotment only that sales point sells,
  • with only a name (“Technik”, “Presse”), a block the house keeps.

A held place is never on sale in the shop. When the person buys through their link, the places go from the hold straight into their checkout; if they leave the checkout, the places return to the hold, not to the shop. A hold ends when everything is bought (fulfilled), when you release it (released) or at its expires_at (expired), and its places then go back on sale.

To book places for someone straight away, free or paid outside Usetix, see booking tickets.

Co-organizer tokens work with holds on their assigned events; allotments for sales points are the venue’s.

GET /admin/events/:event_slug/occupancy

The seat map’s state: every place, whole table and standing area with what is happening to it, the open holds and the orders behind sold places. Events without a seating plan return 404.

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

The response carries an ETag. Send it back as If-None-Match to get 304 Not Modified while nothing changed.

Response:

{
  "revision_id": 812,
  "counts": { "free": 812, "cart": 4, "held": 36, "blocked": 4, "sold": 1100 },
  "categories": [
    { "id": 3, "name": "Parkett", "color": "#2563EB" }
  ],
  "holds": [
    {
      "id": 41,
      "name": "Erika Muster",
      "email": "erika@example.com",
      "color": "#9D174D",
      "kind": "reservation",
      "expires_at": "2026-11-14T17:00:00Z",
      "place_count": 4,
      "in_checkout": false
    }
  ],
  "orders": {
    "abcd1234efgh5678": { "code": "7K3Q9D2A", "name": "Jane Doe", "status": "paid" }
  },
  "places": [
    { "key": "seat:9001", "id": 5501, "category_id": 3, "state": "held", "hold_id": 41 },
    { "key": "seat:9002", "id": 5502, "category_id": 3, "state": "sold", "order": "abcd1234efgh5678" },
    { "key": "seat:9003", "id": 5503, "category_id": 3, "state": "free" }
  ],
  "tables": [
    { "key": "table:77", "id": 310, "category_id": 4, "capacity": 6, "state": "free" }
  ],
  "standing": [
    { "key": "standing:12", "id": 90, "capacity": 200, "sold": 120, "cart": 2, "holds": [{ "id": 43, "quantity": 10 }], "free": 68 }
  ]
}
Field Notes
counts Places by state, whole tables counted by their seats and standing areas by quantity.
holds[].kind reservation, allotment or block.
holds[].in_checkout Someone is paying for places of this hold right now.
orders The orders behind sold places, by order public_id. guest_list: true marks a guest-list party.
places[].id The event_place_ids value for the write endpoints below.
places[].state free, cart (in someone’s checkout), held (a reservation or allotment), blocked (kept for the house) or sold.
places[].hold_id The hold that keeps the place, or the hold it was bought from.
places[].order The order behind a sold place.
tables[] Tables sold as a whole, with the same states. Their id is the event_table_ids value.
standing[] Standing areas by quantity. Their id is the event_capacity_pool_ids value.

A key whose value would be null is left out: holds[].email and expires_at, orders[].name and guest_list, and places[].hold_id and order appear only when they have a value. places[].key here names the place on the seat map’s canvas (seat:<id>); a hold’s places[].key is the seat’s logical key that MCP and the assistant use (seat-a-1).

GET /admin/events/:event_slug/holds

Lists the event’s holds with the hold fields, the open ones by default. status filters by open, fulfilled, released or expired; all lists every hold. Response: 200 with { "holds": [...] }.

POST /admin/events/:event_slug/holds

Holds places in one go. Places that are sold or in someone’s checkout are left out; places the house keeps move over to the new hold; places reserved for another person or a sales point stay theirs. Nothing is created when none of the places can be held.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "event_place_ids": [5501, 5502, 5503, 5504],
    "name": "Erika Muster",
    "email": "erika@example.com",
    "expires_at": "2026-11-14T17:00:00Z",
    "send_link": true
  }' \
  https://app.usetix.io/admin/events/spring-showcase/holds

Parameters:

Parameter Description
event_place_ids Numbered places, from the occupancy’s places[].id.
event_table_ids Whole tables.
event_capacity_pool_ids and quantity Places in standing areas: quantity in each given area, at most what is free there.
name Who the places are for, or why the house keeps them. A name or an email is required.
email The person’s email. It makes the hold a reservation with a buy link.
note A note for your team. Never shown to the person.
expires_at ISO 8601 time in the future when the hold ends and its places go back on sale. Omit for no end.
sales_point_id A sales point’s id: the hold becomes its allotment, named after it unless you give a name. Venue tokens only.
send_link true emails the buy link to email right away.

Supports Idempotency-Key. Response: 201 Created with the hold and a Location header. Nothing to hold returns 422 with { "errors": { "base": ["…"] } }; an expires_at that doesn’t read as a time or an unknown sales_point_id returns 422 naming that field.

GET /admin/events/:event_slug/holds/:id

Returns one hold, open or ended.

Response:

{
  "id": 41,
  "name": "Erika Muster",
  "email": "erika@example.com",
  "note": "Called on Monday",
  "kind": "reservation",
  "sales_point": null,
  "status": "open",
  "color": "#9D174D",
  "expires_at": "2026-11-14T17:00:00Z",
  "link_sent_at": "2026-11-08T10:12:03Z",
  "buy_url": "https://example-shop.usetix.io/reservation/x8Kq2mZ4pV7rT1sN0bW5cY3d",
  "attendee_count": 4,
  "places": [
    { "id": 5501, "key": "k3v9QzT2bW8mN4xR", "label": "Parkett · Reihe 5 · Platz 3" }
  ],
  "tables": [],
  "standing": [],
  "created_at": "2026-11-08T10:12:01Z",
  "closed_at": null
}

PATCH /admin/events/:event_slug/holds/:id

Changes name, email, note or expires_at of an open hold. Send expires_at: null to remove its end. Returns 200 with the hold; an ended hold returns 422.

DELETE /admin/events/:event_slug/holds/:id

Releases the hold: its places go back on sale. Someone already paying can still finish. Returns 200 with the hold, now released.

POST /admin/events/:event_slug/holds/:id/places

Adds places to an open hold, with the same parameters and rules as creating one. Returns 200 with the hold, or 422 when none of the places could be added.

DELETE /admin/events/:event_slug/holds/:id/places

Takes the given places (event_place_ids, event_table_ids, event_capacity_pool_ids) out of the hold and puts them on sale. A hold left with nothing is released. Returns 200 with the hold.

POST /admin/events/:event_slug/holds/:id/link_delivery

Emails the buy link of a reservation to its email, in the shop’s look, again if it was sent before. Returns 200 with the hold; link_sent_at records when. Holds without an email and holds that ended return 422.

You can also hand the buy_url over yourself. It opens the person’s places with the tickets that sell them, then the ordinary checkout with their name and email filled in. Purchase limits per order and per buyer don’t apply to held places.

POST /admin/events/:event_slug/place_release

Puts the given places back on sale, whichever holds kept them. Returns 204 No Content.

Hold fields

Field Type Notes
id integer The hold’s ID.
name string | null Who it is for, or why the house keeps the places.
email string | null The person’s email.
note string | null Your team’s note.
kind string reservation, allotment or block.
sales_point object | null id and name of the sales point an allotment is for.
status string open, fulfilled, released or expired.
color string The colour the seat map paints its places in.
expires_at string | null ISO 8601 UTC end.
link_sent_at string | null When the buy link was last emailed.
buy_url string | null The person’s buy link. Only reservations have one. Share it only with them.
attendee_count integer Places held, standing places counted by quantity.
places, tables, standing object[] What it holds now, each with id and the label printed on tickets; places with their seat key, the one MCP and the assistant use; standing areas with their quantity.
created_at, closed_at string ISO 8601 UTC. closed_at is set once the hold ended.

Usetix forgets who a hold was for 30 days after its event: name becomes a dash, email and note become null.