Integration walkthrough - Headout API docs

Overview

Headout API for API Partner
Headout API for Affiliates

API Partner teams control the full booking experience inside their own product. The flow below starts with discovery and ends with post-booking updates.

Standard flow (NORMAL)
Seatmap flow (SEATMAP)

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.

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.

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.

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.

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.

​Overview

​Discover what to sell

​Check availability

​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

​Validate seats

​Create the booking

​Keep the user updated

​Discover what to show

​Show product details

​Check availability

​Send the customer to checkout

Overview

Discover what to sell

Check availability

Create the booking

Keep the user updated

Integration paths

Discover what to sell

Check show availability

Select seats

Validate seats

Create the booking

Keep the user updated

Discover what to show

Show product details

Check availability

Send the customer to checkout