Venue
Venue iframe
GET
For products with
Replace
Parse incoming messages with
2. Listen for
Without
Handling
inventorySelectionType: SEATMAP. Returns an HTML page that renders the Headout-hosted seat selection UI. Embed this endpoint as an iframe in your integration. Domain whitelisting required — contact the Headout partnerships team to register your domain.
The seatmap iframe is a Headout-hosted, fully interactive seat selection UI. Embed it to support seatmap products without building custom seat selection. The endpoint returns a rendered HTML page — not a JSON payload. No API key is required; access is controlled by domain allowlisting.
Domain whitelisting
The iframe enforces an allowlist of permitted embedding domains. Before going live, contact the Headout partnerships team and provide the domain(s) you intend to embed the iframe on. Headout will add your domain toALLOWED_DOMAINS.
- Requests from domains not on the allowlist return
403 Forbidden. - The allowlist is matched against the browser-sent
Refererheader. - Ensure the page embedding the iframe does not apply a
Referrer-Policyofno-referrerorstrict-origin-when-cross-origin— either setting suppresses the header and every embed request will return403. - Subdomains of a whitelisted domain are automatically permitted — whitelisting
example.comalso allowswww.example.com. - The iframe sets a
Content-Security-Policy: frame-ancestorsresponse header scoped to your domain to prevent embedding from unauthorised origins.
Embedding
Add the iframe to your page with the product ID substituted in thesrc URL:
3023 with the actual product ID. The iframe container must have a defined height — height="100%" requires the parent element to have an explicit height set, otherwise the iframe collapses to 0px and nothing renders.
postMessage events
The iframe communicates with the parent page viawindow.postMessage. All messages in both directions are JSON-stringified in the following envelope:
JSON.parse(event.data).
Initialisation sequence
The iframe does not load seats automatically. After embedding, you must complete the handshake and pass the selected show slot. 1. Sendinit once the iframe has loaded
iframeInitCompleted, then send initPlugin
| Option | Type | Required | Description |
|---|---|---|---|
date | string | Yes | Selected show date in yyyy-MM-dd format (from Availabilities response) |
time | string | Yes | Selected show time in HH:mm:ss format (from Availabilities response) |
currencyCode | string | Yes | Currency code for pricing (e.g. GBP, USD) |
deviceType | string | No | Controls layout — DESKTOP (default) or MOBILE |
initPlugin the map renders empty — no seats will be displayed.
Outbound events
All outbound events follow the envelope{ "type": "...", "data": { ... } }.
Map lifecycle
| Type | Data | When |
|---|---|---|
initializingSeatmapStarted | — | Map has begun rendering after initPlugin. Show a loading state. |
initializingSeatmapCompleted | — | Map is fully rendered and interactive. Hide the loading state. |
Seat events
| Type | Data | When |
|---|---|---|
onSeatAdded | { seat } | A single seat was added to the selection. |
onSeatRemoved | { seat } | A single seat was removed from the selection. |
onSeatSelectionChanged | { seats } | Fires on every seat add or remove — reflects the full current selection. |
onSeatSelectionSubmitted | { seats } | User confirmed their selection — use these seats for Validate and Booking. |
onSeatSelectionSubmitted:
Inventory events
Emitted on initial seatmap load (afterinitPlugin) and on every subsequent setInventorySlot call.
| Type | Data | When |
|---|---|---|
inventoryUpdateStarted | — | Inventory fetch has begun. Show a loading state. |
inventoryUpdateCompleted | — | Inventory loaded and map is ready. Hide the loading state. |
Price filter events
| Type | Data | When |
|---|---|---|
onPriceFilterClick | { filters } | User clicked a price filter option. |
applyFilterClicked | { numberOfPricesSelected } | User applied the selected price filters (mobile). |
clearFilterClicked | — | User cleared all applied filters (mobile). |
priceListOpened | — | Price filter list opened (mobile). |
priceListClosed | — | Price filter list closed (mobile). |
priceListClicked | — | Price list was clicked (mobile). |
Zoom events
| Type | Data | When |
|---|---|---|
onZoomLevelChanged | — | Zoom level changed. |
onZoomInButtonClick | — | Zoom in button clicked. |
onZoomOutButtonClick | — | Zoom out button clicked. |
onZoomResetButtonClick | — | Zoom reset button clicked. |
Other
| Type | Data | When |
|---|---|---|
log | { data } | Internal debug message from the iframe. |
Seat object
Each item in theseats array (from onSeatAdded, onSeatRemoved, onSeatSelectionChanged, and onSeatSelectionSubmitted) has the following shape:
| Field | Type | Description |
|---|---|---|
id | string | SVG seat identifier. Pass as ids in selectSeats and as id in addSeat / removeSeat. |
seatCode | string | Pass as inventorySeatIds in the Validate and Booking requests. |
inventorySlotId | string | Pass as inventoryId in the Validate and Booking requests. |
price | number | Per-seat price in the selected currency. |
originalPrice | number | Pre-discount price. |
currency | string | Local currency symbol (e.g. £). |
discounted | boolean | true if a discount is applied to this seat. |
seatNumber | string | Seat number — use for display purposes. |
seatRow | string | Row identifier — use for display purposes. |
seatSection | string | Section name — use for display purposes. |
color | string | Hex color assigned to this seat’s price tier — use for display matching. |
description | string | Seat or category description — use for display purposes. |
remaining | number | Seats remaining in this category. |
maxAvailable | number | Maximum seats bookable per transaction in this category. |
Inbound commands
The parent can send commands to the iframe after initialisation:| Type | Data | Description |
|---|---|---|
setInventorySlot | { options: { date, time, currencyCode } } | Update the show slot without re-embedding. date format is yyyy-MM-dd, time format is HH:mm:ss. Triggers inventoryUpdateStarted / inventoryUpdateCompleted. |
selectSeats | { ids: string[] } | Pre-select seats by seat id. |
addSeat | { id: string } | Add a seat by seat id. |
removeSeat | { id: string } | Remove a seat by seat id. |
Security
The iframe only accepts messages originating from the whitelistedparentOrigin. Send all messages to https://www.headout.com as the target origin and ensure your domain is registered in ALLOWED_DOMAINS.
Next steps
OnceonSeatSelectionSubmitted fires, pass the returned seat data to Validate to confirm availability, then proceed to Booking.
Path Parameters
Product ID of the seatmap product.
Response
Seat selection HTML page rendered successfully.