Skip to content

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:

  1. The event is cancelled. The seat goes off sale (event_cancelled).
  2. The ticket was already scanned for this show. The seat goes off sale (already_scanned). Someone may be sitting in it.
  3. Staff chose a destination. The seat goes there.
  4. 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.
  5. 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-preview
  • GET /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:

FieldValues
seat_destinationdefault (back where it came from), open_sale, house_hold, off_sale
seat_house_hold_idRequired with house_hold. A hold on the same event.
seat_off_sale_noteOptional with off_sale. Max 200 characters.
confirm_door_risktrue 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: true by default. Only send it when staff have confirmed the doors are updated.

Next