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.