Skip to main content
POST
/
api
/
public
/
v1
/
booking
cURL
curl --location 'https://www.headout.com/api/public/v1/booking' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--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"
  }
}'
{
  "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
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.

productId
string

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

inventorySeatIds
string[] | null

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

variantInputFields
object[] | null

Booking-level input fields applicable to the whole booking rather than individual customers.

price
object

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

Response

200 - application/json

Booking created successfully

bookingId
string
required

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

variantId
string
required

The variant (tour option) that was booked.

startDateTime
string<date-time>
required

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

product
object
required

Summary of the product and variant booked.

customersDetails
object
required

All customers included in this booking.

price
object
required

Total price paid for this booking.

status
enum<string>
required

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
voucherUrl
string
required

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

creationTimestamp
integer<int64>
required

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

partnerReferenceId
string | null

Your own reference ID for this booking, set when capturing. Useful for correlating Headout bookings with your internal order system.

variantInputFields
object[]
tickets
object[] | null

Individual tickets associated with this booking. Populated after successful fulfillment.

seatInfo
object[] | null

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