Integration walkthrough

Overview

Headout API for API Partner
Headout API for Affiliates

The Get Product response includes an inventorySelectionType field. Use it to determine which integration flow applies:

NORMAL: Standard general-admission products (guided tours, timed-entry attractions, activities). Customer selects a date, variant, and optional time slot; no seat or section assignment required.
SEATMAP: Products with specific seat selection. Customer picks individual seats from an interactive seatmap.
SVG: Products with section-based seating. Customer selects a section; seat assignment is automatic.

Normal flow
Seatmap flow
SVG flow

Discover what to sell

Discover supported cities

API: List CitiesStart by fetching the cities Headout supports. Each product is tied to a city.What you get: city code, city name, country, and coordinates.

Browse products for a city

API: List ProductsUse the city code to fetch the products available in that market. Filter by collection, category, currency, or language.What you get: product summaries, titles, pricing, media, and category metadata.

Open product details

API: Get ProductPull the full product record for variants, policies, media, and booking fields required later in the flow.What you get: variants, pricing tiers, input field definitions, cancellation and reschedule policies, and deep-link URLs.

Read each variant’s inputFields carefully. They define the guest data you must collect before creating the booking.

Check availability

Browse date-level availability

API: List availabilities - NormalFetch available dates and pricing for a specific variant within a date range. Use this to build a calendar or date picker before the customer selects a specific slot.What you get: available dates, availability status (LIMITED, UNLIMITED, CLOSED), remaining count, and minimum pricing per date.

remaining: 1000 is a sentinel value indicating unlimited availability.

Check live slot inventory

API: List Inventory - NormalOnce the customer selects a date, fetch real-time slot inventory. Inventory is slot-based and can change quickly, so do not cache it.What you get: time slots, pax types, netPrice, and headoutSellingPrice.

Never sell below headoutSellingPrice. Pax types and prices can vary by slot even for the same variant.

Collect guest details

Don’t worry! The current integration continues to work as-is, with input fields from Get Product remaining valid for booking submissions. Only ~5% of slots have supplier-specific overrides that differ from the variant definition, and this step ensures those edge cases are handled correctly.

Fetch booking input fields for the selected slot

API: Get Inventory Details by IDOnce the customer picks a slot, fetch the exact input fields required for that inventory before rendering your booking form. Fields vary by inventory — common examples include pickup location, drop-off address, nationality, passport number, meal preference, hotel name, age, and weight.Pass the id from the selected inventory as inventoryId.What you get: an inputFields array where each field carries a numeric id, a dataType (STRING, INT, ENUM, LOCATION, etc.), validation rules, and a level (PRIMARY_CUSTOMER or ALL_CUSTOMER).

Use level to decide which guests need each field: PRIMARY_CUSTOMER fields are collected once for the lead traveller only; ALL_CUSTOMER fields must be collected for every traveller in the booking.

Create the booking

API: Create BookingSubmit the selected slot, guest details, and pax counts. The booking starts in UNCAPTURED, then moves to PENDING after payment capture.What you get: a booking object with a bookingId and initial status.

Keep the user updated

Track the booking status

APIs: Get Booking · List BookingsPoll the booking or listen for webhooks. When the booking reaches COMPLETED, the ticket data is ready to show to the customer.Status progression: PENDING → COMPLETED / FAILED / CANCELLED

Receive updates automatically

APIs: Create Webhook · Webhook PayloadRegister a webhook so status changes arrive automatically instead of relying on polling.What you receive: bookingId, new status, and eventTimestamp.

Change or cancel a booking

APIs: Cancel Booking · Reschedule BookingUse the booking policies returned by product details to decide whether a customer can change or cancel a booking.

Integration paths

There are three ways to integrate seatmap products. Choose the one that fits your use case.

Iframe (low effort)

Embed the Headout seat selection iframe. Partners receive seat IDs and pricing via iframe events, then call Validate and proceed to booking. Fastest path to selling seatmap products.APIs: Seatmap Availabilities · Venue Iframe · Seat Map Validate · Create Booking

Full UI (high effort)

Build the seat selection UI using Headout’s inventory and venue layout data. Full control over the experience.APIs: Seatmap Availabilities · List Inventory - Seatmap · Venue Map · Seat Map Validate · Create Booking

No UI (section-based)

Partner exposes available sections. Customer selects a section. Partner books any available seats from that section. No seat-level UI required.APIs: Seatmap Availabilities · List Inventory - Seatmap · Seat Map Validate · Create Booking

Discover what to sell

Discover supported cities

API: List CitiesStart by fetching the cities Headout supports. Each product is tied to a city.What you get: city code, city name, country, and coordinates.

Browse products for a city

API: List ProductsUse the city code to fetch the products available in that market.What you get: product summaries, titles, pricing, media, and category metadata. Look for inventorySelectionType: SEATMAP to identify seatmap products.

Open product details

API: Get ProductPull the full product record for variants, policies, media, and booking fields.What you get: variants (including the variantId to use in seatmap APIs), pricing tiers, input field definitions, and policies.

Check show availability

API: Seatmap AvailabilitiesPass productId and variantId to get available show dates and time slots with per-slot pricing and remaining seat counts.What you get: available dates and slots, each with startTime, nested pricing (headoutSellingPrice and netPrice), and remaining seat count. Carry the variantId forward.

Pricing here reflects the cheapest available seat on that slot. Actual per-seat prices come from the Inventory API.

Select seats

Choose one integration path:

Full UI

Fetch seat inventory

API: List Inventory - SeatmapPass productId, variantId, date, and startTime to get all available seats for that show, grouped by section.What you get: a show-level inventoryId (carry this to Validate and Booking), all available seats with seatCode, row, seatNumber, seatType, and per-seat pricing.

Render the venue map

API: Venue MapFetch the venue layout SVG URL. The SVG represents the physical layout — sections, rows, and seat positions. Static per product — call once and cache.Use the SVG and Inventory response together:

Render the SVG as the base layout. Each seat has an identifier matching the seatCode in the Inventory response.
Mark seats returned by Inventory as selectable with their price.
Mark seats absent from Inventory as unavailable.
When a customer clicks a seat, collect its seatCode for Validate and Booking.

No UI (section-based)

Fetch seat inventory

API: List Inventory - SeatmapPass productId, variantId, date, and startTime to get all available seats grouped by section.What you get: a show-level inventoryId, all seats grouped by sectionName with seatCode and per-seat pricing.

Present sections to the customer

From the Inventory response, extract the unique sections and display them to the customer (e.g. Stalls, Royal Circle, Grand Circle). The customer picks a section — not individual seats.

Select seats on behalf of the customer

Take any available seatCode values from the customer’s chosen section and pass them as inventorySeatIds in the Booking request. The customer does not see or pick individual seats.

Iframe

Whitelist your domain

Before going live, contact the Headout partnerships team with the domain(s) you intend to embed the iframe on. Headout will add them to the ALLOWED_DOMAINS list.

Requests from un-whitelisted domains return 403 Forbidden.
The check is against the browser-sent Referer header — ensure the embedding page does not set Referrer-Policy: no-referrer or strict-origin-when-cross-origin.
Subdomains of a whitelisted domain are automatically permitted.

Embed the iframe

API: Venue IframeAdd the iframe to your page using the productId:

<iframe
  id="seatmap-iframe"
  src="https://www.headout.com/api/public/v2/products/{productId}/seatmap/"
  width="100%"
  height="100%"
></iframe>

The iframe does not load seats automatically — you must complete the initialisation handshake via postMessage.

Initialise and pass the show slot

Once the iframe loads, send init. The iframe responds with iframeInitCompleted. Then send initPlugin with the date, time, and currency from the Availabilities response:

const iframe = document.getElementById('seatmap-iframe');
iframe.addEventListener('load', () => {
  iframe.contentWindow.postMessage(JSON.stringify({ type: 'init' }), 'https://www.headout.com');
});

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.headout.com') return;
  let msg;
  try { msg = JSON.parse(event.data); } catch { return; }
  if (msg.type === 'iframeInitCompleted') {
    iframe.contentWindow.postMessage(JSON.stringify({
      type: 'initPlugin',
      data: { options: { date: '2026-06-15', time: '19:30', currencyCode: 'GBP' } },
    }), 'https://www.headout.com');
  }
});

Collect selected seats

Listen for onSeatSelectionSubmitted. The seats array in the event payload contains everything needed for Validate and Booking:

Field	Use
`seatCode`	Pass as `inventorySeatIds` in Validate and Booking
`inventorySlotId`	Pass as `inventoryId` in Validate and Booking
`price`	Per-seat price in the selected currency

See Venue Iframe for the full event reference.

Collect guest details

Don’t worry! The current integration continues to work as-is, with input fields from Get Product remaining valid for booking submissions. Only ~5% of inventories have supplier-specific overrides that differ from the variant definition, and this step ensures those edge cases are handled correctly.

Fetch booking input fields for the selected show

API: Get Inventory Details by IDUse the show-level inventoryId from the seatmap inventory response (or inventorySlotId from the iframe event) to fetch the exact input fields required before rendering your booking form.What you get: an inputFields array where each field carries a numeric id, a dataType (STRING, INT, ENUM, LOCATION, etc.), validation rules, and a level (PRIMARY_CUSTOMER or ALL_CUSTOMER).

Validate seats

Validate selected seats

API: Seatmap ValidateSubmit inventoryId and selected seatCodes for a live availability and pricing check before checkout.What you get: per-seat isAvailable and current pricing. Always check the validationErrors array — a 200 response does not mean all seats are bookable.

Error code	Meaning
`SEAT_UNAVAILABLE`	Seat exists but cannot be booked
`SEAT_NOT_FOUND`	Seat code does not exist in this venue
`ADJACENCY_RULE_VIOLATION`	Seat combination violates a venue seating rule

ADJACENCY_RULE_VIOLATION means the seat itself is available — it is the combination that violates the venue’s rule. Prompt the customer to adjust their selection.Common rules: seats must be consecutive (no gaps); selecting an end seat that leaves a single unsold neighbour is not allowed; all seats at a table must be selected together.

Use the prices from this response in the Booking request. Prices can change between Inventory and Validate.

Create the booking

API: Create BookingSubmit the booking with variantId, inventoryId, and inventorySeatIds (the seat codes from any section — mix freely across sections). Customer details go in customersDetails.customers[] with inputFields for NAME, EMAIL, and PHONE. Set price.amount to the sum of netPrice from the Validate response — the booking will be rejected if the price doesn’t match.What you get: a booking object with bookingId, status UNCAPTURED, and a seats array confirming the reserved seats.

Capture the booking

API: Update BookingSet status to PENDING with a partnerReferenceId to confirm and trigger fulfilment.

Keep the user updated

Track the booking status

Receive updates automatically

APIs: Create Webhook · Webhook PayloadRegister a webhook so status changes arrive automatically instead of relying on polling.

SVG flow products use a venue map SVG to show customers the venue layout. The customer selects a section, and seat assignment is handled automatically at booking time.

Discover what to sell

Discover supported cities

API: List CitiesStart by fetching the cities Headout supports. Each product is tied to a city.What you get: city code, city name, country, and coordinates.

Browse products for a city

Open product details

API: Get ProductPull the full product record for variants, policies, media, and booking fields.What you get: variants (each representing a section, identified by variantId), pricing tiers, input field definitions, and policies.

Check availability

API: List AvailabilitiesPass productId and variantId (the section) to get available dates for that section.What you get: available dates, availability status (LIMITED, UNLIMITED, CLOSED), remaining count, and pricing per date.

Get venue map and inventory

Fetch the venue map

API: Venue MapFetch the venue layout SVG using the product ID. The SVG is static per product — call once and cache it.

Each section in the SVG has a class attribute in the format tour-id-{variantId}. Match the chosen variant ID from the product response to the SVG element’s class to identify the correct section.

Fetch inventory

API: List Inventory - NormalPass the selected date and variantId (the section). The response includes all available show times for that section on the selected date, each with pricing and an inventoryId required for booking.

Create the booking

API: Create BookingSubmit the booking with variantId, inventoryId, and customer details. Seat assignment is handled automatically.What you get: a booking object with bookingId and initial status UNCAPTURED.

Capture the booking

API: Update BookingSet status to PENDING with a partnerReferenceId to confirm and trigger fulfilment.

Keep the user updated

Track the booking status

Receive updates automatically

APIs: Create Webhook · Webhook PayloadRegister a webhook so status changes arrive automatically instead of relying on polling.

Affiliate teams show Headout inventory in their own storefront and hand the booking off to Headout checkout.

Discover what to show

Discover supported cities

API: List CitiesFetch the cities where Headout has inventory, then use that list to scope the storefront.What you get: city code, city name, country, and coordinates.

Browse collections and categories

APIs: List Collections · List Categories · List SubcategoriesUse these optional filters to organize the storefront and help users browse faster.What you get: IDs and names for filtering the Products API.

Show product details

Fetch products

API: List ProductsRetrieve the products for a city and optionally filter by collection, category, or subcategory.What you get: product titles, pricing, ratings, media, and deep-link URLs.

Products may have inventorySelectionType: NORMAL, SEATMAP, or SVG. For affiliates, the booking flow is identical across all types — customers are always sent to Headout checkout via the deep-link URL.

Open product details

API: Get ProductUse this when you need the full content for a product page, including media, variants, and policy summaries.What you get: Rich product content including canonicalUrl, localeSpecificUrls (localized deep-links per language), pricing per variant, and hasInstantConfirmation flag.

See the section below on variant metadata for how to handle properties and propertiesV2 in the response.

Use localeSpecificUrls[languageCode] (or canonicalUrl as fallback) to send users directly to Headout’s checkout for the selected language. This is how Affiliate bookings are attributed to your account.

Check availability

Browse date-level availability

API: List availabilities - NormalFetch available dates and pricing for a specific variant within a date range. Use this to show a calendar or highlight available dates on your product page.What you get: available dates, availability status (LIMITED, UNLIMITED, CLOSED), remaining count, and commissionAmount per date.

remaining: 1000 is a sentinel value indicating unlimited availability.

Send the customer to checkout

Deep-link to Headout checkout

Use the canonicalUrl or localeSpecificUrls[languageCode] from the product details response to send the customer directly to Headout’s checkout page. Bookings made via your deep-link are automatically attributed to your affiliate account.

Track your bookings

List attributed bookings

API: List BookingsRetrieve all bookings attributed to your account within a date range. Use this to reconcile earnings, audit attribution, and build your own reporting dashboard.What you get: booking status, product name, price in local currency and USD, your earnings in USD, attribution type (WEB or APP), UTM parameters, and basic user info.

Use attributionType to understand how each booking was attributed — WEB for cookie-based deep-link attribution, APP for mobile app.

Get a single booking

API: Get BookingFetch the full details for a specific booking by its bookingId. Returns 404 if the booking does not belong to your account.What you get: the same fields as the list response, scoped to one booking.

Start here

Build

Reference

Updates

Overview

Discover what to sell

Check availability

Collect guest details

Create the booking

Keep the user updated

Integration paths

Iframe (low effort)

Full UI (high effort)

No UI (section-based)

Discover what to sell

Check show availability

Select seats

Collect guest details

Validate seats

Create the booking

Keep the user updated

Discover what to sell

Check availability

Get venue map and inventory

Create the booking

Keep the user updated

Discover what to show

Show product details

Check availability

Send the customer to checkout

Track your bookings

​Overview

​Discover what to sell

​Check availability

​Collect guest details

​Create the booking

​Keep the user updated

​Integration paths

Iframe (low effort)

Full UI (high effort)

No UI (section-based)

​Discover what to sell

​Check show availability

​Select seats

​Collect guest details

​Validate seats

​Create the booking

​Keep the user updated

​Discover what to sell

​Check availability

​Get venue map and inventory

​Create the booking

​Keep the user updated

​Discover what to show

​Show product details

​Check availability

​Send the customer to checkout

​Track your bookings

Overview

Discover what to sell

Check availability

Collect guest details

Create the booking

Keep the user updated

Integration paths

Discover what to sell

Check show availability

Select seats

Collect guest details

Validate seats

Create the booking

Keep the user updated

Discover what to sell

Check availability

Get venue map and inventory

Create the booking

Keep the user updated

Discover what to show

Show product details

Check availability

Send the customer to checkout

Track your bookings