React checkout
Seats
Reserved-seat checkout uses a host-supplied seat-map catalog. The SDK renders the map and holds seats; your BFF loads map + best-available data.
Event-page door (do not lie about the mode)
Public reserved is sellable when event.status is on_sale. Buyer Event GET
does not return seating_ready. Do not read an attested flag. Do not tell
guests to “Open seat map” or “pick your table.”
Use resolveBuyerLayoutPresentation from @axyn/web-sdk:
ticketing_layout_mode | On-sale door |
|---|---|
reserved_seat | Find N (Get tickets / Continue). Browse house is secondary. seat_select_default=pick_seat may open the house first; Find N stays available. |
section_and_type | TicketPanel area Ask: place cards (section_name, location_note, from-price, leftover). One Guests stepper. Price beat when an area has multiple types. No Find N. No chair dots. Never mount SeatPicker. |
general | Tier + quantity. Unchanged. |
After the seat-map loads: no sections or no chairs → “Tickets are not available” (no empty House View chrome). Chairs exist but none are guest-selectable → “Sold out. None left.” — not “coming soon.”
Browse house opens a room of places: STAGE plus named section blocks.
For stacked houses, blocks use stored section rectangles when
pos_x / pos_y / width / height are all present and size is greater
than zero; aisles are packed for readability. For curved families (fan,
horseshoe, bowl, end-stage), the overview draws one section silhouette per
place from saved chair coordinates (convex hull), with a curved stage apron.
When chairs have coordinates but the house classifies as stacked, hulls still
replace stored section rectangles. Individual chair dots appear only after the
guest picks a section (chip or place). Pure zone blocks without chair coordinates keep
rectangles. Sold-out places stay visible
and say Sold out in text; they do not open a chair grain.
After a section is chosen, Map / List toggle the chair grain. Browse-house List
is a sit-together offer catalog (place, then named row runs), not a chair dump.
When every fitting row is the same price, List collapses to one stub plus a
row-letter strip. Named runs return only when rows differ in all-in or cap.
It uses the same Accessible filter. Rows stay listed when chairs have no map
coordinates. Companions are optional paid
chairs next to a wheelchair space, not a forced pair. Do not invent doors or
silhouettes beyond what seat coordinates imply.
section_id on Find N is supported — pass it when the guest picks a priced
place. Find N paints result.stills on the result card; a missing still never
blocks hold. Best value / Best view / Closest are a client sort of together
runs. Closest uses the last room they pointed at (default the stage). It is
hidden when chairs have no stored pos_x / pos_y. Do not send a preference
to best-available-group.
When the spine uses seats
Find N (Find N great seats) is the filled primary when
seat_select_default is find_n (the default). Browse house stays a
ghost control until the guest asks. A hold that would leave one leftover
chair in a row returns orphan_seat; the strip shows one sentence and
another option. Aisle gaps are not orphans. Restricted seats show one
limited-view sentence and require Acknowledge before Continue; pay
repeats the same sentence.
CheckoutSpineRoot opens SeatSelectionDrawer only when both are true:
event.ticketing_layout_mode === 'reserved_seat'- You pass
seatCatalog(aSeatMapCatalogClient)
Otherwise phase 3 is general admission (TierSelectionDrawer).
Host contract: SeatMapCatalogClient
type SeatMapCatalogClient = {
fetchSeatMap: () => Promise<SeatMap>;
fetchBestAvailableGroup: (input: {
n: number;
section_id?: string;
}) => Promise<BestAvailableResult>;
};
The SDK does not call AXYN seat-map HTTP routes directly from the browser
with a tenant secret. You implement SeatMapCatalogClient against your own
same-origin backend, which talks to AXYN server-side with x-api-key
(catalog:read). Confirm seat-map and best-available paths in live OpenAPI /
Headless API.
Pass seatCatalog into the spine
import { CheckoutSpineRoot, type SeatMapCatalogClient } from '@axyn/web-sdk';
const seatCatalog: SeatMapCatalogClient | null =
event.ticketing_layout_mode === 'reserved_seat'
? createSeatMapCatalogClient(event.event_id)
: null;
<CheckoutSpineRoot
/* …other required props… */
seatCatalog={seatCatalog}
/>;
Factory shape (same-origin BFF):
function createSeatMapCatalogClient(
ownedEventId: string
): SeatMapCatalogClient {
const base = `/api/catalog/events/${encodeURIComponent(ownedEventId)}`;
return {
async fetchSeatMap() {
const response = await fetch(`${base}/seat-map`, {
headers: { Accept: 'application/json' },
});
// unwrap your { success, data } envelope
return data;
},
async fetchBestAvailableGroup({ n, section_id }) {
const response = await fetch(`${base}/best-available-group`, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({ n, ...(section_id ? { section_id } : {}) }),
});
return data;
},
};
}
Map payload shape: SeatMap (sections[] → seats[] with status, labels,
optional pos_x / pos_y). Types: @axyn/web-sdk (SeatMap, SeatMapSeat,
…).
What the SDK does after selection
On Continue in SeatSelectionDrawer, the spine:
- Sets qty to
draft.seatIds.length - Calls
actions.holdSeats()→POST /v1/seats/hold(buyer JWT) - Refreshes preview totals
- Advances to add-ons or review
Hold starts after restricted ack, not at tap and not at Apple Pay. Change
seats calls actions.changeSeats() → POST /v1/seats/release with the same
hold_owner, then returns to Find N / Browse house.
After pay, GET /v1/orders/:id tickets include buyer-safe seat identity
(section_name, row_label, seat_number, seat_label,
restricted_note, companion_seat_label). Live Pass paints those fields.
It never prints hold_type or House / Artist / Press names.
Do not invent a separate client-side inventory hold. Totals still come from AXYN preview / order responses.
Exports (custom UI)
Prefer the spine. For a custom picker surface:
| Export | Role |
|---|---|
SeatSelectionDrawer | Full phase-3 drawer (used by spine) |
SeatPicker | Find N + Browse house + Map/List after a section |
SeatPickerList | Accessible list of chairs, including those without coords |
ZoneCardPicker | section_and_type cards. Never mount with SeatPicker |
SeatMapRenderer | SVG map. Overview = places; section = chairs. Optional overCapSeatIds mutes over-budget chairs (omit/empty = no mute). |
BestAvailableCta | Find N. Pass section_id when the guest picked a place |
SeatConfirmStrip | Selected-seat confirmation copy |
| Layout helpers | resolveBuyerLayoutPresentation, parseTicketingLayoutMode |
| Geometry helpers | reconcileSelection, seatDisplayLabel, listViewSeats |
CSS
import '@axyn/web-sdk/seat-picker.css';
import '@axyn/web-sdk/zone-cards.css';
Import with the rest of your checkout stylesheets. See Quickstart.
Honesty limits
- Seat-map catalog is host BFF–backed today; the SDK only consumes
SeatMapCatalogClient. - Best-available alternatives may still include
type: waitliston the wire. Buyer UI (BestAvailableCta, TicketPanel) drops that row and never shows Join. An empty house is Sold out; leftover chairs that cannot sit N are not. - Fixture-only harness checkout is GA-oriented; reserved seat needs a live (or BFF-backed) map.
- Examples use ENG-651 keys only (
theater-house,fan-theater,opera-horseshoe,arena-bowl,sports-secondary,end-stage-concert). Never branch on a partner venue name.
Next
- Organizer seating (venue house, seating-ready, publish)
- Checkout spine
- Quickstart
- Stripe wrappers
- Anti-patterns