Skip to content

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

  1. A sandbox secret key (axyn_sk_test_...) as AXYN_API_KEY. Contract: Credentials.
  2. Scope catalog:write on that key, or a staff JWT with event.write.
  3. Your sandbox TENANT_ID, VENUE_ID, and draft EVENT_ID. Use ids from your sandbox tenant. Never paste a production tenant id into examples.
  4. Live OpenAPI at https://api.axyn.events/openapi.json (or Postman at https://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.

ModeChartPublish seating gate
generalNone (GA / standing-room)None. Hard floor. Do not call seating-ready.
section_and_typeSections (capacity by type)seating_ready plus at least one section with capacity > 0
reserved_seatNamed seats on a mapseating_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.

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 → 422 accessible_intent_required
  • restricted chairs without restricted_ack: true → 422 restricted_ack_required
  • named house-hold chairs without a valid access_code → 422 house_hold_locked or invalid_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_owner counted together) → 429 seat_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: true and the sections you saved.
  • Apply returns seat/section counts. Event is no longer seating-ready.
  • seating:ready with { "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.

StarterSeed --keyLayout family
Small theatertheater-housestacked
Fan theaterfan-theaterfan
Opera horseshoeopera-horseshoehorseshoe
Arenaarena-bowlbowl
Sportssports-secondarybowl
End-stage concertend-stage-concertend_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_mode after draft (422 layout_mode_locked).
  • Switching Guests buy in Admin without confirming when a chart exists.
  • Leaving reserved sellable seats without a ticket type.
  • Putting tenant_id in the JSON body or using another tenant's ids.
  • Putting AXYN_API_KEY in a browser bundle.
  • Using axyn_sk_live_... while following this sandbox guide.

Next