Skip to main content
PUT
/
api
/
public
/
v1
/
booking
/
{id}
cURL
curl --location --request PUT 'https://www.headout.com/api/public/v1/booking/<some-booking-id>' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "status": "PENDING",
    "partnerReferenceId": "<some-partner-reference-id>"
}'

{
  "bookingId": "<string>",
  "partnerReferenceId": "<string>",
  "variantId": "<string>",
  "startDateTime": "2023-11-07T05:31:56Z",
  "product": {
    "id": "<string>",
    "name": "<string>",
    "variant": {
      "id": "<string>",
      "name": "<string>"
    }
  },
  "customersDetails": {
    "count": 123,
    "customers": [
      {
        "personType": "<string>",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "<string>",
            "name": "<string>",
            "value": "<string>"
          }
        ]
      }
    ]
  },
  "variantInputFields": [
    {
      "id": "<string>",
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "price": {
    "amount": 123,
    "currencyCode": "<string>"
  },
  "status": "UNCAPTURED",
  "voucherUrl": "<string>",
  "tickets": [
    {
      "publicId": "<string>",
      "url": "<string>",
      "type": "PDF_URL"
    }
  ],
  "seatInfo": [
    {
      "section": "<string>",
      "row": "<string>",
      "seatNumber": "<string>",
      "seatCode": "<string>"
    }
  ],
  "creationTimestamp": 123
}

Authorizations

​
Headout-Auth
string
header
required

Path Parameters

​
id
string
required

ID of the booking to update.

Body

application/json
​
status
enum<string>
required

Set to PENDING to capture the booking and trigger fulfillment.

Available options:
PENDING
​
partnerReferenceId
string
required

Your internal reference ID for this booking (e.g., order number). Stored on the booking for reconciliation purposes.

Response

200 - application/json

Booking updated successfully

​
bookingId
string

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

​
partnerReferenceId
string | null

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

​
variantId
string

The variant (tour option) that was booked.

​
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.

​
customersDetails
object

All customers included in this booking.

​
variantInputFields
object[]
​
price
object

Total price paid for this booking.

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

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

​
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.

​
creationTimestamp
integer

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