Create a new booking - Headout API docs

curl --location 'https://www.headout.com/api/public/v2/bookings/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          { "id": "NAME", "value": "John Doe" },
          { "id": "EMAIL", "value": "john@example.com" },
          { "id": "PHONE", "value": "+14155551234" }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}'

{
  "bookingId": "126890",
  "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": []
}

POST

api

public

bookings

curl --location 'https://www.headout.com/api/public/v2/bookings/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          { "id": "NAME", "value": "John Doe" },
          { "id": "EMAIL", "value": "john@example.com" },
          { "id": "PHONE", "value": "+14155551234" }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}'

{
  "bookingId": "126890",
  "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": []
}

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 to capture the booking and trigger fulfillment. Bookings not captured within one hour are automatically moved to CAPTURE_TIMEDOUT.

curl --location 'https://www.headout.com/api/public/v2/bookings/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          { "id": "NAME", "value": "John Doe" },
          { "id": "EMAIL", "value": "john@example.com" },
          { "id": "PHONE", "value": "+14155551234" }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}'

{
  "bookingId": "126890",
  "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": []
}

Authorizations

Headout-Auth

string

header

required

Body

application/json

productId

string

required

The product to book. Obtain from the product listing endpoints.

variantId

string

required

The variant (tour option) to book. Obtain from the product's variants list.

inventoryId

string

required

The specific inventory slot (time/date) to book. Obtain from the inventory listing endpoint.

customersDetails

object

required

Information about all customers included in this booking.

Show child attributes

price

object

required

The total price the customer is paying. Validated against current inventory pricing to prevent stale-price bookings.

Show child attributes

inventorySeatIds

string[] | null

Specific seat IDs to reserve, for seatmap-based products. Omit for non-seatmap products.

variantInputFields

object[] | null

Booking-level input fields — collected once for the whole booking, not per customer. Submit fields whose level is BOOKING here; per-customer fields (PRIMARY_CUSTOMER, ALL_CUSTOMER) belong inside customersDetails.customers[].inputFields.

level (who you collect from) and dataType (what shape the value takes) are independent — a BOOKING-level field can be any dataType, and a LOCATION dataType field can be at any level.

Show child attributes

Response

Booking created successfully in UNCAPTURED state

bookingId

string

Headout's unique identifier for this booking. Use this for all subsequent operations (capture, cancel, reschedule).

partnerReferenceId

string | null

Your own reference ID for this booking, set when capturing via Update Booking.

variantId

string

The variant (tour option) that was booked.

status

enum<string>

Current lifecycle state of the booking. See 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.

Available options:

UNCAPTURED,

PENDING,

COMPLETED,

CANCELLED,

FAILED,

CAPTURE_TIMEDOUT

startDateTime

string<date-time>

Scheduled start time for the experience in local time, with no timezone offset (format yyyy-MM-dd'T'HH:mm:ss).

product

object

Summary of the product and variant booked.

Show child attributes

customersDetails

object

All customers included in this booking.

Show child attributes

variantInputFields

object[] | null

Booking-level input fields applicable to the whole booking.

Show child attributes

price

object

Total price paid for this booking.

Show child attributes

voucherUrl

string

URL to the booking voucher PDF. Available once the booking reaches PENDING or COMPLETED status.

tickets

object[] | null

Show child attributes

seatInfo

object[] | null

Seat assignment details for seatmap-based products. Null for non-seatmap products.

Show child attributes

creationTimestamp

integer<int64>

Unix epoch timestamp (seconds) when this booking was first created.

Venue iframe

List all bookings

⌘I