Skip to main content

How to Configure an Overflow Add-on

Overflow add-ons sell extra seats beyond a suite's capacity (shipped recently — the mechanics are strict). The backend sanitizer silently discards misconfigured overflow add-ons, so a wrong config doesn't error — the add-on just never appears. This checklist prevents that.

Use this when: a team wants to offer "add N more seats" on a suite.

Where this happens: add-on configuration lives in the Cortex admin (the config plane — it writes the same tbl_* tables the fan backend reads). The seat mapping in step 4 is data setup; if you're doing this for the first time, confirm the current process with the team before touching a live store.

The checklist (all required)​

  1. Category — addonCategory = 'overflow', with isForcedAddon = false and isInformational = false. ⚠️ Forced + overflow is explicitly rejected (discarded with a WARN in the logs).
  2. Scope — addonLevel = 'suite_level', with both suiteId and gameEventCode set. Overflow is always per-suite, per-event.
  3. Exactly one price option. The v1 contract is a single price for all overflow seats — multi-price is deferred.
  4. Map the physical seats in tbl_suite_overflow_seat_mapping — one row per seat, keyed (suiteId, sectionName, rowName, seatNumber). This mapping is the inventory:
    • the seats are not in tbl_seats;
    • every seat-count value (default / min / max) is clamped to the number of mapped rows;
    • an empty mapping silently drops the add-on from the catalog — if the add-on isn't showing, check the mapping first.
  5. Keep mapped seats contiguous within each row. TM Host holds are sent as a min→max range per (section, row) — a gap in the middle means TM assigns seats in the gap instead of the ones you mapped.

How it behaves once live​

  • Fans see it as a normal optional add-on with a per-seat price.
  • Holds use specific seats on both vendors (Host: reserveTickets with accept_best_available: false; Archtics: seatsHoldSpecific) — a failed hold fails the item, it doesn't silently substitute seats.

Full matrix and enums: Add-on Types — Reference.