Skip to main content

​
How to use these APIs?

Workflow

​
Headout Booking Partners

Headout offers different API products for various business needs. Make sure to choose the right one for your specific use case.
Booking partners have access to the full suite of APIs — from product discovery through to booking, ticketing, and post-booking management.
1

Get Supported Cities

API: List CitiesFetch the list of cities supported by Headout. Use this to populate a city picker in your UI. Every product is scoped to a city, so this is always the starting point.What you get: city code, city name, country, and coordinates.
2

Fetch Products for a City

API: List ProductsPass a cityCode to retrieve all available products. Paginate using offset and limit. You can optionally filter by collectionId, categoryId, or apply a currencyCode and languageCode for localization.What you get: Product listings with IDs, titles, pricing summary, media, and category metadata.
3

Get Full Product Details

API: Get ProductFetch complete details for a specific product. It returns all variants, their cancellation and reschedule policies, and input fields required at booking time.What you get: Variants, pricing tiers, input field definitions, policies, media, and deep-link URLs.
Read each variant’s inputFields carefully — these define exactly what guest data you must collect before calling the Booking API.
4

Check Real-Time Availability

API: List InventoryFor a specific product and date range, fetch live inventory. This returns available time slots, pax types (Adult, Child, etc.), and pricing per slot. Always call this in real time — never cache inventory.What you get: Time slots with startDateTime, endDateTime, available pax types, netPrice, and headoutSellingPrice (the minimum selling price you must respect).
Do not sell below headoutSellingPrice. Pax types and prices can vary between slots even for the same variant. See MSP Limitation Product List for products with specific MSP constraints.
5

Create a Booking

API: Create BookingSubmit the booking with the selected time slot, pax counts, and guest details collected from the input fields. The booking is created in UNCAPTURED; then call Update Booking to move it to PENDING after payment capture.What you get: A booking object with a bookingId and initial status UNCAPTURED.
StatusMeaning
PENDINGPayment captured, booking confirmed with supplier
UNCAPTUREDPre-payment state — does not lock inventory or price
6

Track Booking Status & Retrieve Tickets

APIs: Get Booking · List BookingsPoll the booking status or use webhooks (see next step). Once status is COMPLETED, the tickets array is populated with ticket objects for delivery to the customer.Status progression:
StatusAction
PENDINGTreat as confirmed, await ticket generation
COMPLETEDTicket ready — deliver to customer
FAILEDBooking failed — surface error to user
CANCELLEDBooking cancelled
For products where hasInstantConfirmation: false, tickets may take up to ~30 minutes. The voucherUrl always reflects the latest state and can be shown to the customer immediately.
7

Receive Real-Time Updates via Webhooks

APIs: Create Webhook · Webhook PayloadRegister a webhook endpoint to receive POST notifications whenever a booking status changes. This is the recommended alternative to polling.What you receive: bookingId, new status, and eventTimestamp.
Set up your webhook before going live. See the webhook payload reference for retry behavior and response expectations.
8

Cancel or Reschedule (if needed)

APIs: Cancel Booking · Reschedule BookingIf a customer requests a change, submit a cancellation or reschedule request. Eligibility is determined by the cancellationPolicy and reschedulePolicy returned in the Product Details API — always check these before surfacing the option to the user.What you get: An acknowledgement response with success and a message describing the outcome. Final status is delivered via webhook.

​
High-Level Integration Flow

Headout inventory follows a strict hierarchy: City → Product → Variant → Time Slot → Booking → Ticket

​
Typical End-User Journey

  1. User selects a city
  2. Partner fetches all products for that city
  3. User selects a product and variant
  4. User selects date and time slot
  5. Partner fetches real-time availability
  6. User enters guest details and completes payment
  7. Booking is confirmed
  8. Ticket is generated (instant or delayed)
  9. Booking updates are received via webhooks

​
Product Discovery, Variants & Policies

​
Cities & Products

  • Products are always fetched at a city level
  • B2B APIs return all products, without B2C groupings (e.g. bestsellers)

​
Variants

A single product can have multiple variants. Variants can differ by many parameters, including but not limited to:
  • Inclusions and exclusions
  • Cancellation or reschedule eligibility
  • Meeting point or pickup details
  • Ticket type and fulfillment behavior
  • Pricing and availability patterns
Variants must be treated as independent purchasable units, not as metadata.

​
Cancellation & Reschedule Policies

Cancellation and reschedule behavior is defined explicitly in the Product Details API. Important characteristics:
  • Cancellation is allowed or not allowed (true / false)
  • Rescheduling is allowed or not allowed (true / false)
  • Policies may differ across products and across variants of the same product
Partners must:
  • Read and rely on the API response
  • Surface the correct policy to users before booking
  • Not assume uniform behavior across variants

​
Inventory, PaxTypes & Pricing

​
Real-Time Inventory

  • Availability is fetched at variant + date level
  • Inventory is time-slot based and highly dynamic
  • Inventory must always be fetched in real time

​
PaxTypes

  • Defined at time-slot level since we are aggregating the suppliers at the backend
  • Can vary between slots for the same variant
  • Examples include Adult, Child, EU Adult, Non-EU Adult
PaxTypes must be rendered dynamically with no hard-coded assumptions. See Pax Types.

​
Pricing

Each inventory response includes:
  • netPrice → partner cost
  • headoutSellingPrice → minimum selling price (MSP)
Partners must not sell below MSP. See MSP Limitation Product List for products with specific constraints, and Group Pricing for products priced per group.

​
Guest Details & Dynamic Input Fields

Some variants require additional guest information beyond name/email/phone.

​
Input Fields

Input fields are defined dynamically in the Product Details API for each variant and specify:
  • Whose details are needed for the booking (level is PRIMARY_CUSTOMER, ALL_CUSTOMERS, or BOOKING)
  • Data type (Boolean, String, Integer, Enum, Location)
  • Optional predefined values (for all ENUM and some LOCATION fields)
Form rendering must be fully driven by the API response. See Input Fields.

​
Guest Objects

  • A guest object is required for every pax booked
  • Empty input field objects for each guest must be added if no fields are required for those guests
  • This ensures reconciliation between pax count and guest data

​
Booking Lifecycle & Statuses

​
Two-Step Booking Model

StatusMeaning
UNCAPTUREDOptional pre-payment state
PENDINGPayment done, booking confirmed
COMPLETEDTicket generated and available
FAILEDBooking failed
CANCELLEDBooking cancelled
Key notes:
  • UNCAPTURED does not lock price or inventory
  • PENDING can be treated as confirmed
  • Booking statuses are fluid, not terminal

​
Ticket Generation & hasInstantConfirmation

Each product includes a hasInstantConfirmation flag:
ValueMeaning
trueTicket generated immediately
falseTicket generated with delay
Typical timelines:
  • Instant confirmation: < 1 minute (avg)
  • Delayed generation: ~30 minutes on average, p99 up to 1 day before experience
For delayed products:
  • Booking should still be shown as confirmed
  • Ticket generation is asynchronous
  • Voucher updates automatically when the ticket is ready

​
Voucher URL & Ticket Delivery

​
Voucher URL — Key Points

  • Acts as the single source of truth
  • Shows booking status, ticket state, and experience instructions
  • Can be Headout-branded or re-skinned by the partner by masking out the Headout logo and contact details
  • Guides users clearly for delayed ticket generation
The voucher URL should be treated as the authoritative post-booking artifact. It reflects the latest booking and ticket state, even when tickets are generated later or booking status changes. Voucher messaging automatically adapts for delayed tickets.

​
Ticket Types

Available in the booking details response. Each ticket object includes a type field:
TypeURL presentDescription
QRCODENoQR code rendered inline
BARCODENoBarcode rendered inline
TEXTNoPlain text ticket code
PDF_URLYesLink to downloadable PDF ticket
HTML_URLYesLink to hosted HTML ticket page
APPLE_WALLET_URLYesApple Wallet pass URL
GOOGLE_WALLET_URLYesGoogle Wallet pass URL

​
Sandbox vs Production Behavior

​
Sandbox Environment

Only a limited set of products transition to COMPLETED automatically. See Fulfilment on Sandbox for the full list.
  • All other sandbox bookings may remain in PENDING
  • Sandbox should be used to validate: booking flow, webhooks, voucher rendering, and status transitions

​
Production Environment

  • Real supplier behavior applies
  • Ticket generation follows hasInstantConfirmation
  • Cancellation and reschedule rules are enforced strictly

​
Webhooks & Booking Updates

Webhooks are essential to:
  • Track ticket generation
  • Receive cancellation or reschedule updates
  • Handle failures
  • Keep booking state in sync
Partners must assume:
  • Status transitions are non-linear
  • Completed bookings can still be cancelled (ex: in case of venue closures etc)