Skip to content

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_modeOn-sale door
reserved_seatFind N (Get tickets / Continue). Browse house is secondary. seat_select_default=pick_seat may open the house first; Find N stays available.
section_and_typeTicketPanel 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.
generalTier + 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:

  1. event.ticketing_layout_mode === 'reserved_seat'
  2. You pass seatCatalog (a SeatMapCatalogClient)

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:

  1. Sets qty to draft.seatIds.length
  2. Calls actions.holdSeats() → POST /v1/seats/hold (buyer JWT)
  3. Refreshes preview totals
  4. 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:

ExportRole
SeatSelectionDrawerFull phase-3 drawer (used by spine)
SeatPickerFind N + Browse house + Map/List after a section
SeatPickerListAccessible list of chairs, including those without coords
ZoneCardPickersection_and_type cards. Never mount with SeatPicker
SeatMapRendererSVG map. Overview = places; section = chairs. Optional overCapSeatIds mutes over-budget chairs (omit/empty = no mute).
BestAvailableCtaFind N. Pass section_id when the guest picked a place
SeatConfirmStripSelected-seat confirmation copy
Layout helpersresolveBuyerLayoutPresentation, parseTicketingLayoutMode
Geometry helpersreconcileSelection, 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: waitlist on 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