> ## Documentation Index
> Fetch the complete documentation index at: https://partner.headout.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a new booking
> We are soon moving to **v2 APIs** and **v1** will be deprecated. Switch to **v2** using the version selector above.
Create a new booking in `UNCAPTURED` state.
The booking flow is two-step: call this endpoint first to reserve the slot and receive a `bookingId`, then call [Update Booking](/api-partner/v1/bookings/update) to capture the booking and trigger fulfillment. Bookings not captured within one hour are automatically moved to `CAPTURE_TIMEDOUT`.
**Rate limit:** Create Booking is capped at **100 requests per rolling 30-minute window** per API key. The limit counts **every request received** — successful (`200`), failed (e.g. `400`), and requests already rejected with `429` all count toward the window, not just bookings created. Once you cross the limit, requests return `429 Too Many Requests` with `error.code` = `E_RATE_LIMIT_EXCEEDED`. The response includes a `retry-after` header with the number of seconds to wait (e.g. `1608`), and the error message states the same wait time in human-readable form. Use the `retry-after` value to schedule your next call.
## OpenAPI
````yaml POST /api/public/v1/booking/
openapi: 3.1.0
info:
title: Headout API Docs
version: 0.0.1
servers:
- url: https://www.headout.com
description: Production server
- url: https://www.sandbox-headout.com
description: Sandbox server
security: []
paths:
/api/public/v1/booking/:
post:
tags:
- Bookings
summary: Create a new booking
description: >-
We are soon moving to **v2 APIs** and **v1** will be
deprecated. Switch to **v2** using the version selector above.
Create a new booking in `UNCAPTURED` state.
The booking flow is two-step: call this endpoint first to reserve the
slot and receive a `bookingId`, then call [Update
Booking](/api-partner/v1/bookings/update) to capture the booking and
trigger fulfillment. Bookings not captured within one hour are
automatically moved to `CAPTURE_TIMEDOUT`.
**Rate limit:** Create Booking is capped at **100 requests per
rolling 30-minute window** per API key. The limit counts **every request
received** — successful (`200`), failed (e.g. `400`), and requests
already rejected with `429` all count toward the window, not just
bookings created. Once you cross the limit, requests return `429 Too
Many Requests` with `error.code` = `E_RATE_LIMIT_EXCEEDED`. The response
includes a `retry-after` header with the number of seconds to wait (e.g.
`1608`), and the error message states the same wait time in
human-readable form. Use the `retry-after` value to schedule your next
call.
operationId: v1CreateBooking
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BookingRequest'
responses:
'200':
description: Booking created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
example:
bookingId: '126890'
voucherId: '415872'
partnerReferenceId: null
variantId: '25525'
status: UNCAPTURED
startDateTime: '2025-04-12T19:30:00'
product:
id: '18969'
name: Bali Swing Experience
variant:
id: '25525'
name: Standard Entry
customersDetails:
count: 1
customers:
- personType: ADULT
isPrimary: true
inputFields:
- id: NAME
name: Name
value: John Doe
- id: EMAIL
name: Email
value: john@example.com
- id: PHONE
name: Phone
value: '+14155551234'
seatInfo: null
variantInputFields: []
price:
amount: 77.08
currencyCode: USD
creationTimestamp: 1712953295
voucherUrl: https://www.headout.com/voucher/126890?key=AAAD6AAAABhsDVGl...
tickets: []
'429':
description: >-
Rate limit exceeded. Create Booking is capped at 100 requests per
rolling 30-minute window per API key. The response carries a
`retry-after` header (seconds until the next request is allowed),
and the error message states how long to wait before retrying.
headers:
retry-after:
description: >-
Number of seconds to wait before sending another Create Booking
request.
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
timestamp:
type: integer
format: int64
description: Response timestamp in milliseconds.
traceId:
type: string
description: Trace identifier for the request.
traceTokenOriginal:
type: string
description: Original trace token for the request.
error:
type: object
properties:
code:
type: string
description: Error code (`E_RATE_LIMIT_EXCEEDED`).
message:
type: string
description: >-
Human-readable message stating how long to wait before
retrying.
example:
timestamp: 1787825956750
traceId: 5bc7926d5ffe466c
traceTokenOriginal: 892b5cc0f80f832e10b1be8a7d0702be
error:
code: E_RATE_LIMIT_EXCEEDED
message: Rate limit exceeded. Please try again in 26m 48s.
security:
- apiKeyAuth: []
x-codeSamples:
- lang: curl
source: |
curl --location 'https://www.headout.com/api/public/v1/booking/' \
--header 'Headout-Auth: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"variantId": "2671",
"inventoryId": "402612775",
"customersDetails": {
"count": 1,
"customers": [
{
"personType": "GENERAL",
"isPrimary": true,
"inputFields": [
{
"id": "NAME",
"value": "adult test"
},
{
"id": "EMAIL",
"value": "test@email.com"
},
{
"id": "PHONE",
"value": "+919888888787"
},
{
"id": "CUSTOM_97179",
"value": "some pickup point"
},
{
"id": "CUSTOM_125551",
"value": "+919888888787"
}
]
}
]
},
"price": {
"amount": 120.0,
"currencyCode": "AED"
}
}'
components:
schemas:
BookingRequest:
type: object
required:
- variantId
- inventoryId
- customersDetails
properties:
productId:
type: string
description: The product to book. Obtain from the product listing endpoints.
variantId:
type: string
description: >-
The variant (tour option) to book. Obtain from the product's
variants list.
inventoryId:
type: string
description: >-
The specific inventory slot (time/date) to book. Obtain from the
inventory listing endpoint.
inventorySeatIds:
type:
- array
- 'null'
items:
type: string
description: >-
Specific seat IDs to reserve, for seatmap-based products. Omit for
non-seatmap products.
customersDetails:
type: object
description: Information about all customers included in this booking.
properties:
count:
type: integer
description: Total number of customers in this booking.
customers:
type: array
items:
type: object
description: Individual customer details.
properties:
personType:
type: string
description: >-
Pricing category for this customer (e.g., `ADULT`,
`CHILD`, `SENIOR`). Must match a type defined in the
variant's pricing.
isPrimary:
type: boolean
description: >-
Marks the lead customer whose contact details (name,
email, phone) are used for booking confirmation and
voucher delivery.
inputFields:
type: array
items:
type: object
description: Input fields for customer details.
properties:
id:
type: string
description: >-
Field identifier matching an `inputField` defined in
the variant (e.g., `NAME`, `EMAIL`, `PHONE`, or a
`CUSTOM_*` field).
value:
type: string
description: The customer's response for this field.
variantInputFields:
type:
- array
- 'null'
items:
type: object
properties:
id:
type: string
description: >-
Field identifier (e.g., `TRANSPORTATION_TYPE`,
`PICKUP_POINT`).
value:
type: string
description: The submitted value for this field.
description: >-
Booking-level input fields applicable to the whole booking rather
than individual customers.
price:
type: object
description: >-
Total booking price — the sum of the inventory `netPrice` field
across all pax types. Use `netPrice`, not `price` or
`headoutSellingPrice`. Validated against current inventory pricing
to prevent stale-price bookings.
properties:
amount:
type: number
format: double
description: Total price amount for all customers combined.
currencyCode:
type: string
description: >-
Currency code matching the currency used when fetching inventory
pricing. See [Currency
Codes](/guide/enums-and-error-codes#currency-codes).
Booking:
type: object
properties:
bookingId:
type: string
description: >-
Headout's unique identifier for this booking. Use this `bookingId`
for all subsequent operations (capture, cancel, reschedule).
voucherId:
type: string
description: >-
Identifier of the voucher issued for this booking. Pass it to [Get a
voucher](/api-partner/v2/vouchers/get) to retrieve the structured
voucher payload.
partnerReferenceId:
type:
- string
- 'null'
description: >-
Your own reference ID for this booking, set when capturing. Useful
for correlating Headout bookings with your internal order system.
variantId:
type: string
description: The variant (tour option) that was booked.
startDateTime:
type: string
format: date-time
description: >-
Scheduled start time for the experience in local time, with no
timezone offset (format `yyyy-MM-dd'T'HH:mm:ss`).
product:
type: object
description: Summary of the product and variant booked.
properties:
id:
type: string
description: Headout product ID.
name:
type: string
description: Display name of the product (e.g., "Wicked - Broadway Musical").
variant:
type: object
description: The specific variant (seating category, option) that was booked.
properties:
id:
type: string
description: Headout variant ID.
name:
type: string
description: >-
Display name of the variant (e.g., "Grand Circle", "Standard
Admission").
customersDetails:
type: object
description: All customers included in this booking.
properties:
count:
type: integer
description: Total number of customers across all person types.
customers:
type: array
items:
type: object
description: Individual customer details.
properties:
personType:
type: string
description: >-
Pricing category for this customer (e.g., `ADULT`,
`CHILD`, `SENIOR`).
isPrimary:
type: boolean
description: >-
Whether this is the lead customer for the booking. Only
one customer should be primary.
inputFields:
type: array
items:
type: object
description: Collected form field data for this customer.
properties:
id:
type: string
description: >-
Field identifier (e.g., `NAME`, `EMAIL`, `PHONE`, or
`CUSTOM_*`).
name:
type: string
description: Human-readable label for this field.
value:
type: string
description: The submitted value for this field.
variantInputFields:
type: array
items:
type: object
description: >-
Booking-level input fields (applicable to the whole booking rather
than individual customers).
properties:
id:
type: string
description: >-
Field identifier (e.g., `TRANSPORTATION_TYPE`,
`PICKUP_POINT`).
name:
type: string
description: Human-readable label for this field.
value:
type: string
description: The submitted value for this field.
price:
type: object
description: Total price paid for this booking.
properties:
amount:
type: number
format: double
description: Total price amount for all customers combined.
currencyCode:
type: string
description: >-
Currency code for the price amount. See [Currency
Codes](/guide/enums-and-error-codes#currency-codes).
status:
type: string
description: >-
Current lifecycle state of the booking. See [Booking
Status](/guide/enums-and-error-codes#booking-status).
- `UNCAPTURED`: Created but not yet captured. Does not lock
inventory or price. Auto-expires to `CAPTURE_TIMEDOUT` after 1 hour.
- `PENDING`: Payment captured — confirmed with supplier. Treat as
confirmed; show to the customer as a confirmed booking.
- `COMPLETED`: Fulfilled — tickets are available in the `tickets`
array.
- `CANCELLED`: Cancelled by partner, customer, or Headout.
- `FAILED`: Booking failed due to a payment or system error.
- `CAPTURE_TIMEDOUT`: Not captured within 1 hour of creation; can no
longer be captured.
enum:
- UNCAPTURED
- PENDING
- COMPLETED
- CANCELLED
- FAILED
- CAPTURE_TIMEDOUT
voucherUrl:
type: string
description: >-
URL to the booking voucher PDF. Available once the booking reaches
`PENDING` or `COMPLETED` status.
tickets:
type:
- array
- 'null'
description: >-
Individual tickets associated with this booking. Populated after
successful fulfillment.
items:
type: object
properties:
publicId:
type: string
description: >-
Unique identifier for this ticket, usable for support and
lookup.
url:
type:
- string
- 'null'
description: >-
URL for the ticket. Present for `PDF_URL` and `HTML_URL`
types. Null for `QRCODE`, `BARCODE`, and `TEXT` types.
type:
type: string
enum:
- PDF_URL
- HTML_URL
- QRCODE
- BARCODE
- TEXT
description: Ticket delivery format.
seatInfo:
type:
- array
- 'null'
description: >-
Seat assignment details for seatmap-based products. Null for
non-seatmap products.
items:
type: object
properties:
section:
type: string
description: >-
Section name within the venue (e.g., "Orchestra",
"Mezzanine").
row:
type: string
description: Row identifier within the section.
seatNumber:
type: string
description: Seat number within the row.
seatCode:
type: string
description: Unique code identifying the specific seat.
creationTimestamp:
type: integer
format: int64
description: Unix epoch timestamp (seconds) when this booking was first created.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Headout-Auth
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.