Custom API
Seat lifecycle
Reference only. Not a decision unless cited in product/DECISIONS.md.
Seat lifecycle
A reserved seat follows its ticket. When the ticket ends (void, refund, or
cancel), the seat is released in the same step. You never have to free a
seat by hand, and a seat is never left sold with nobody holding it.
Who this is for
Engineers building organizer tools on a reserved-seat event: void, refund, house holds, and the seat map.
Where a released seat goes
AXYN checks these in order and uses the first that applies:
- The event is cancelled. The seat goes off sale (
event_cancelled). - The ticket was already scanned for this show. The seat goes off sale
(
already_scanned). Someone may be sitting in it. - Staff chose a destination. The seat goes there.
- A door may still have the old barcode. If a scanner downloaded an
offline door list in the last 12 hours, the seat goes off sale
(
door_cache). It comes back on its own once every list downloaded before the release has expired. One login can sit on several devices, so a later download does not count as a refresh. - Otherwise it goes back where it came from. A seat sold from a house hold returns to that hold. Any other seat returns to open sale.
A reissue or comp exchange to the same ticket type moves the seat to the new
ticket, so it stays sold. To another ticket type, the old seat is released
by this rule. Returning a comp to its hold and swapping a
ticket for a voucher release the seat straight away, by the same rule.
Seats in a cart follow the same idea. When a cart expires, an unpaid order is cancelled, or the buyer drops a seat, an open-sale seat goes back on sale and a seat taken from a house hold (with its access code) goes back into that hold.
Preview before you confirm
Show staff what will happen before they void or refund:
GET /v1/tenants/{tenantId}/tickets/{ticketId}/seat-release-previewGET /v1/tenants/{tenantId}/refund-requests/{requestId}/seat-release-preview
Each seat comes back with its label (section, row, seat), ticket type, and
default_destination, worked out by the same rule the release uses. The
event's house_holds are listed for a staff choice. Nothing moves.
Choose a destination
POST /v1/tickets/{ticketId}/void and the refund approve
(POST /v1/tenants/{tenantId}/refund-requests/{requestId}/decision) accept
the same optional fields:
| Field | Values |
|---|---|
seat_destination | default (back where it came from), open_sale, house_hold, off_sale |
seat_house_hold_id | Required with house_hold. A hold on the same event. |
seat_off_sale_note | Optional with off_sale. Max 200 characters. |
confirm_door_risk | true puts the seat on sale even if a door list may still admit the old barcode. |
Leave them out and the seat goes back where it came from. A cancelled event or a scanned ticket always wins over a staff choice.
A void or refund approve with a hold from another event returns 422
seat_house_hold_not_found and changes nothing: the ticket stays active and
a refund request stays pending.
The void response's released_seats lists every seat it moved:
{
"result_code": "ticket_voided",
"released_seats": [
{
"seat_id": "…",
"event_id": "…",
"ticket_id": "…",
"to_status": "held",
"house_hold_id": "…",
"off_sale_reason": null
}
]
}
Refunds
Approving a refund releases the refunded tickets' seats right after the money decision. A partial refund of the money alone (no tickets refunded) leaves seats as they are; the order shows Partially refunded.
Refunds made outside the admin (Stripe dashboard, mass refunds) are caught
by a sweep that runs every minute. It frees any seat still sold behind an
ended ticket, for shows that have not ended yet.
Release or delete a house hold
POST /v1/events/{eventId}/house-holds/{holdId}/release and
DELETE /v1/events/{eventId}/house-holds/{holdId} put the hold's seats on
open sale in one step and report what moved:
{
"released": true,
"seats_released": 12,
"by_ticket_type": [
{ "ticket_tier_id": "…", "name": "Orchestra", "seats": 8 },
{ "ticket_tier_id": "…", "name": "Balcony", "seats": 4 }
]
}
Sold seats forget the hold, so a later refund of one sends it to open sale, not back into a hold you released. Ticket-type counts update from the map straight after, the same way saving the map does.
Seat history
GET /v1/events/{eventId}/seats/{seatId}/history returns every release of
one seat, newest first: when, why (ticket_voided, ticket_refunded,
ticket_cancelled, hold_released, hold_deleted, door_cache_cleared),
from and to, the hold it went to, the off-sale reason and note, and who did
it. Automatic releases have no actor.
Seat released
Every time a seat goes back on open sale, AXYN writes a seat.released
event (event, seat, ticket type) to its outbox. It is internal for now: a
future waitlist listens to it. Partner webhooks do not deliver it.
Counts stay honest
After every release, each ticket type's sellable count is re-read from the map. An off-sale seat stops being sellable. A seat in a house hold counts as held, not for sale.
Common mistakes
- Freeing a seat with a seat-map edit after a void. The void already did it.
- Expecting a scanned ticket's seat back on sale after a refund. It stays off sale until staff put it back.
- Sending
confirm_door_risk: trueby default. Only send it when staff have confirmed the doors are updated.