Custom API
Organizer seating
Reference only. Not a decision unless cited in product/DECISIONS.md.
Organizer seating
Save a venue house, copy it onto a seated event, mark seating-ready, then publish. House and event charts are copies of each other, not a live link.
Who this is for
Venue engineers and organizers who sell section or reserved-seat inventory. General admission (GA) does not use this flow.
What you need first
- A sandbox secret key (
axyn_sk_test_...) asAXYN_API_KEY. Contract: Credentials. - Scope
catalog:writeon that key, or a staff JWT withevent.write. - Your sandbox
TENANT_ID,VENUE_ID, and draftEVENT_ID. Use ids from your sandbox tenant. Never paste a production tenant id into examples. - Live OpenAPI at
https://api.axyn.events/openapi.json(or Postman athttps://api.axyn.events/postman_collection.json).
Sandbox uses the production API host with a test key:
export AXYN_BASE_URL=https://api.axyn.events
Layout modes
Set ticketing_layout_mode when you create or patch the event.
reserved_seat and section_and_type require venue_id. Create or PATCH
without a place returns 422 seated_venue_required. Clearing the place
while seated is refused; switch Guests buy to A ticket first.
| Mode | Chart | Publish seating gate |
|---|---|---|
general | None (GA / standing-room) | None. Hard floor. Do not call seating-ready. |
section_and_type | Sections (capacity by type) | seating_ready plus at least one section with capacity > 0 |
reserved_seat | Named seats on a map | seating_ready plus seats, every sellable seat assigned a ticket type |
In Admin: event Setup → Tickets → Guests buy. The house tab (Areas or Seats) appears only for seated modes. A ticket hides it.
Reserved ticket types are a name and a price. How many chairs is painted on
Seats. Create may send inventory_total 0; Approve copies the painted
count. GA still types a quantity. An area still sets count on Areas.
Changing Guests buy after seats or areas exist is a confirm. Cancel sends
no PATCH. Confirm changes the mode and clears seating_ready. Seat and
area rows stay. After the event leaves draft, Admin radios are disabled
and PATCH /v1/events/{eventId} with a new ticketing_layout_mode
returns 422 layout_mode_locked.
Copy, not a live link
A venue house is geometry stored on the place (has_seating becomes true
after the first save). An event chart is a separate copy on the event.
- Apply copies house → event. Later house edits do not change published or draft events until you apply again.
- Save copies event → house. Later event edits do not change the place until you save again.
- Apply and save both clear
seating_ready. You must mark ready again before publish.
When the place already has seating, save and replace require
confirm_overwrite: true.
Tenant isolation
Tenant comes from the API key (or staff JWT), never from a JSON body. Do not
send tenant_id in the body. For /v1/tenants/{tenantId}/... routes, path
tenantId must match the key's tenant or the call returns 403. Cross-tenant
ids return 404 with no extra hint.
Steps (sandbox)
Replace $TENANT_ID, $VENUE_ID, and $EVENT_ID with ids from your
sandbox. The event must be reserved_seat or section_and_type, linked to
that venue, and still draft.
1. Read or replace the venue house
curl -sS "$AXYN_BASE_URL/v1/tenants/$TENANT_ID/venues/$VENUE_ID/house" \
-H "x-api-key: $AXYN_API_KEY"
Empty house: { "has_seating": false, "sections": [] }.
Replace (confirm when has_seating is already true):
curl -sS -X PUT "$AXYN_BASE_URL/v1/tenants/$TENANT_ID/venues/$VENUE_ID/house" \
-H "x-api-key: $AXYN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"confirm_overwrite": true,
"sections": [
{
"name": "Orchestra",
"display_order": 0,
"seats": [
{ "row_label": "A", "seat_number": "1", "accessible": false }
]
}
]
}'
section_and_type houses may omit seats and set section capacity instead.
Confirm fields in OpenAPI VenueHouseSection.
2. Apply house → event
curl -sS -X POST "$AXYN_BASE_URL/v1/events/$EVENT_ID/venue-house:apply" \
-H "x-api-key: $AXYN_API_KEY"
GA returns 422 layout_not_seated. Missing place: venue_required. Empty
house: house_empty. Apply never downgrades sold or held reserved seats.
3. Assign ticket types
Reserved: every sellable seat needs a ticket type before ready. Use
POST /v1/events/{eventId}/seats:update (OpenAPI). Blocked seats are not
sellable and do not need a type.
One call takes up to 5,000 seat_ids (ENG-1717), so a whole house is one
save. The server writes in chunks and syncs ticket-type inventory once. A
failure partway (seat_update_failed, or seats_not_mutable from a race)
returns written_seat_ids for chairs that already landed; those stay
written and counted. Reload the seat map after any failure; it is the truth.
Zones (section_and_type): PATCH /v1/events/tiers/{tierId} with
section_id (or null to clear). The section must belong to the same
event. Wrong or cross-tenant ids return 404 section_not_found.
4. Mark seating-ready
curl -sS -X POST "$AXYN_BASE_URL/v1/events/$EVENT_ID/seating:ready" \
-H "x-api-key: $AXYN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ready": true}'
GA returns 422 layout_not_seated. Reserved mark-ready also syncs each ticket
type inventory_total to sellable seats on that type (blocked excluded).
Zone mark-ready checks the shared area pool and does not copy section
capacity onto each linked type. Clearing { "ready": false } does not
rewrite quantities.
GET /v1/events/{eventId} does not return seating_ready. Public reserved is
sellable when status is on_sale. Use the seating:ready response, or treat
publish 422 seating_not_ready as the staff gate. Buyer door: Find N is
default, Browse house is secondary. Copy lives in Seats
(resolveBuyerLayoutPresentation).
House-management honesty (ENG-1131)
Schema: 1787370000000_eng1131-seat-honesty-house-hold.ts (columns +
hold/release/expire). Enum cast on release/expire CASE:
1787380000000_eng1131-cast-seat-status-on-release-expire.ts.
Apply with npm run migrate:up in ticketing-service before opening a
seat map — a missing seat.restricted column 500s the GET.
GET /v1/events/{eventId}/seat-map seats also return restricted,
restricted_note (max 200), companion_of_seat_id, house_hold_id,
hold_type, and accessible_released. The map envelope includes
accessible_release_rule (default never) and seat_select_default
(default find_n). seating:ready returns the same two event fields.
Buyer Event GET does not grow extra seating flags.
The seat-map envelope also carries stage_end (ENG-1674): the side of the
chart the stage is on, north (top, small pos_y), east, south,
west, or null. Send stage_end on event create or PATCH (null clears
it); create also keeps accessible_release_rule and seat_select_default.
When it is set, maps draw the house flat as stored, the stage as a straight
bar on that side, and row letters at the start of each row; they never guess
a curved shape. Admin's grid editor still draws the house shape it is
editing; the stored side governs imported houses and the guest map. When it is null, maps infer the house shape
from chair positions. It is how the map is drawn, not inventory, so it can
change while the event is on sale.
Leftover accessible chairs stay off the public pick unless the release
rule is met. House holds and comps are not a sell-out. PATCH the event
with accessible_release_rule to change it. Best-available accepts
accessible_intent and then only searches accessible chairs plus stored
companions.
Apply copies restricted + companion pairs (ids remapped by section / row / number). It does not copy live named holds. Save event → house copies the same flags, not holds.
POST /v1/seats/hold refuses:
- accessible chairs without
accessible_intent: true→ 422accessible_intent_required - restricted chairs without
restricted_ack: true→ 422restricted_ack_required - named house-hold chairs without a valid
access_code→ 422house_hold_lockedorinvalid_access_code(the error never names the hold) - more than 60 hold requests a minute from one buyer session, or 120 from
one IP address → 429
rate limit exceeded - a hold that would leave one IP address holding more than 40 chairs of the
event at once (every session and
hold_ownercounted together) → 429seat_hold_limit_exceeded. Released, expired and sold chairs stop counting. See Errors
Staff create named holds with POST /v1/events/{eventId}/house-holds
(catalog:write). The raw access code is returned once. Rotate with
.../rotate-code. Release remaining held chairs with .../release.
GET seat-map may take ?access_code= to unlock only that hold's chairs
(access_unlocked). Wrong codes leave the map unchanged.
A hold or Find N pick that would leave one leftover available chair in a
row returns 422 orphan_seat. Organizers cannot turn this off.
seat_select_default defaults to find_n.
Two chairs sit together when they share a section and row and their seat numbers differ by that row's stride: the smallest step between numbers across every chair in the row, sold and blocked included (ENG-1716). A 101–117 center steps by 1; odd/even wings (1, 3, 5 / 2, 4, 6) step by 2, so seats 12 and 14 are neighbors. A void or aisle (103 → 110) and a sold or blocked chair are gaps, never neighbors, and never orphans. Keep each wing its own section: a row that mixes odd, even, and 100s numbering in one section has no single stride. A consecutive row that skips a number with no physical gap (no seat 13) reads as a gap, and a consecutive row with every other chair removed from the house reads as a wing. The web SDK applies the same rule to Find N, tap-to-pick, Sit here, the orphan check, and the "side by side" line on the Find N card and pay summary.
Seat-map seats and best-available rank rows in room order: A…Z, then AA, BB (numeric rows 1…9 before 10), then seat number. Browse rows step front to back by drawn depth, then the same room order.
Staff paint honesty on Price jobs: Price (ticket types), Set aside (block /
hold / named holds), Access (A + companion C), View (limited-view R,
optional ≤200 note per chair; gold fill = has a note). Empty note uses “This seat has a limited or
restricted view.” Hold without restricted_ack is 422. The same
sentence is on the confirm strip, Find N card, and pay summary. The hold
timer does not start until the guest acknowledges.
Staff can host or link a shared section photo (view still) with
POST /v1/events/{eventId}/view-stills (JPEG / PNG / WebP, 5 MB, or an
https URL). Price → View has two jobs: Limited view (R / Remove R)
and Show a picture (section or worse chairs). Pick chairs or a section, add one
photo, then the rail shrinks so they can add another. Assign on a section
(PATCH …/sections/{sectionId} view_still_id) or a cluster
(seats:update view_still_id). The cluster still wins. Seat-map and
Find N (best-available-group) return stills plus view_still_id.
Coverage always says this is a shared view, not the guest’s exact chair.
Find N shows the photo on the result card (no map required). Browse
house shows the same photo after a guest opens a section and picks
chairs, then again on the confirm strip. Two sections stack both
photos; the same photo appears once and names both sections. A missing
photo never blocks hold, pay, or publish. Preview shows one optional
photo card when limited-view chairs have no photo; Approve stays enabled.
House apply does not copy stills. GA is unchanged.
GA (ticketing_layout_mode=general) is unchanged. Cross-tenant seat,
hold, or still ids stay 404 with no extra hint.
Staging walk: seating parity acceptance. Section photos: view stills acceptance.
5. Publish
curl -sS -X POST "$AXYN_BASE_URL/v1/events/$EVENT_ID/publish" \
-H "x-api-key: $AXYN_API_KEY"
Seated 422s: seating_not_ready, seating_inventory_required,
seating_tiers_required. GA publish does not check seating.
Save event → house (optional)
After you edit the event chart, copy it back to the place:
curl -sS -X POST "$AXYN_BASE_URL/v1/events/$EVENT_ID/venue-house:save" \
-H "x-api-key: $AXYN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm_overwrite": true}'
That clears seating_ready on the event. Mark ready again before publish.
What success looks like
- House GET returns
has_seating: trueand the sections you saved. - Apply returns seat/section counts. Event is no longer seating-ready.
seating:readywith{ "ready": true }returns"seating_ready": true.- Publish returns the event at
on_sale. - A second event at the same place can apply the same house. Editing one event does not change the other until you save/apply again.
In Admin reserved: Seating Add → Price (types / blocked) → Preview (mark ready, save chart to place). Status publish shows the same seating errors.
When the place already has a chair house (has_seating) and this event
has no chairs, Apply saved chart is the one filled primary on Add.
Starters and CSV stay ghost. We never apply without a click. If Apply
returns house_empty (zone-only house on a reserved event), starters
become the first path. No house: starters first, as before. Events that
already have chairs open the adjuster; Use a different chart can
still Apply with replace confirm.
The adjuster only opens when it can redraw every chair exactly (ENG-1717). A CSV import or applied venue chart it cannot redraw (odd/even wings, voids, 100s numbering, more than 40 per row, unplaced chairs) shows read only on Add: the real map and seat count, Continue to price, and Use a different chart. Continue, switching steps, and leaving the tab never write chairs. To change that house, replace it on purpose; mark accessible, companion, and limited-view seats on Price.
Zone (section_and_type) events use the same house tab (labeled
Areas), not a second shell item. Add is a name + ticket-count list plus Where they sit (one
sentence, venue_section.location_note). Ticket types on Setup are
prices, not places. Areas are not created from those names. Price
attaches a price to a place (exact name match pre-selects). Approve on Preview requires
that sentence on every area with capacity > 0, a visible price on every
sellable area, and every visible price on a place (seating_location_required,
seating_price_required, seating_price_unlinked). Publish does not
use those mark-ready codes, so live events that already have
seating_ready stay on sale.
When the place already has saved areas and this event has none, Apply
saved areas is the filled primary (same ranking, area words).
Organizer copy names places in the room
(Floor, VIP, balcony). Guests pick a place on Get tickets (ENG-643):
place cards show name, where they sit, from-price, and leftover; one Guests
stepper; a price beat when an area has more than one visible type. Ticket types stay on Setup (name + price);
Add shows a read-only type indicator and a running ticket total. Linking
prices to an area is the Price step (ticket_tiers.section_id):
one card per area, price chips (name + listed all-in), and a status
line such as "Guests who buy GA or VIP share these 200 spots." A chip
already on another area shows "Selling on Floor" so moving it is obvious.
Several prices may share one area count after the shared pool is live.
No CSV and no painted chairs. Preview is the guest last look: place name,
where they sit, from-price, leftover, and extra prices only when more than
one visible price sits there. Never seat dots. Catalog GET stamps
section_name and location_note on each tier. Price has a Next: check dock. Seat map GET includes section capacity.
Partner create/update: POST /v1/events/{eventId}/sections /
PATCH /v1/events/{eventId}/sections/{sectionId}.
Buyer Get tickets uses TicketPanel area Ask (place cards, honest hold copy).
A section with capacity 0 can be saved but cannot sell. Approve and
publish require at least one section with capacity > 0
(sellableSectionCount). Approve also requires a non-blank
location_note on every sellable area (ENG-1217), then a visible price on
every sellable area and every visible price on a place (ENG-1218). Publish
does not re-check the note or those price codes, so already-approved
live events stay on sale. Preview labels zero-count No spots yet. and
does not block Approve for a missing price on a 0-count area.
Shared area pool (ENG-765 Slice A): venue_section.capacity is the only
sellable count for that area. Remaining is capacity minus sold + held −
refunded across every ticket type with that section_id. Two prices
on Floor 200 cannot sell 400. Mark-ready must not clone capacity onto
each type. rpc_order_create_atomic and rpc_comp_hold_create_atomic
use that remaining number when section_id is set. Unlinked types still
use inventory_total. Buyer and staff tier lists stamp area_remaining
(same number on every price in the area). Buyer listings also project
inventory_total so older remaining math matches the pool. Sales shows
one remaining line per area (example: Floor 47 of 200 left).
Switching Setup seating mode to reserved_seat restores Add seats
→ Price → Preview (house starters and CSV). Reserved inventory is
seats, not zone rows — a capacity-only section list does not skip the
starter picker.
House starters (ENG-651)
Admin Step 1 offers six generic houses. Same editor after you pick one (sections, rows × seats, place, accessible, autosave). Shape is a layout family, not a second map.
| Starter | Seed --key | Layout family |
|---|---|---|
| Small theater | theater-house | stacked |
| Fan theater | fan-theater | fan |
| Opera horseshoe | opera-horseshoe | horseshoe |
| Arena | arena-bowl | bowl |
| Sports | sports-secondary | bowl |
| End-stage concert | end-stage-concert | end_stage |
No Thrust starter. No partner venue names in keys or labels. CSV is the
escape hatch for odd reserved outlines
(ENG-739). In Admin, staff
map vendor columns, confirm, preview the same chart chrome as a starter,
then commit through seats:replace-grid. Mapping is this paste only.
Names-only files need a layout family — we do not guess a bowl from
labels. Caps: 5,000 seat rows and 24 sections. Comma CSV or paste; Excel
and TSV are refused. Zone events reject seat import
(layout_not_reserved_seat). Partner exact-header import is unchanged.
Sample (AXYN headers):
section_name,row_label,seat_number,pos_x,pos_y,accessible
Orchestra,A,1,20,30,true
Orchestra,A,2,34,30,false
Vendor headers such as Section,Row,Seat,X,Y work after staff map them.
Local QA seed (SEAT tenant, wraps the same generators as Admin):
cd ticketing-service
npm run seed:seating-house-fixture -- --key=fan-theater
Re-runs skip when that fixture title already exists. seed:reserved-seat-demo
now uses the Small theater generator too.
Admin Playwright (Fan theater + one row, chart stays curved — 5 consecutive passes required when this spec changes):
cd axyn-admin
npm run test:e2e:local -- e2e/seating-house-starters.spec.ts
Zone authoring + switch back to reserved (ENG-650 — 5 consecutive passes when this spec changes):
cd axyn-admin
npm run test:e2e:local -- e2e/seating-zones.spec.ts
Common mistakes
- Calling seating-ready or apply on
general. That is rejected. - Expecting house edits to update events without apply.
- Saving over an existing house without
confirm_overwrite: true. - Publishing a seated event before
seating_ready. - PATCHing
ticketing_layout_modeafter draft (422layout_mode_locked). - Switching Guests buy in Admin without confirming when a chart exists.
- Leaving reserved sellable seats without a ticket type.
- Putting
tenant_idin the JSON body or using another tenant's ids. - Putting
AXYN_API_KEYin a browser bundle. - Using
axyn_sk_live_...while following this sandbox guide.
Next
- Seat lifecycle (void, refund, and hold release)
- Seat maps (buyer SDK)
- Headless API (same
/v1buy path after the house is published) - Testing
- Errors
- API reference
- Changelog