Get a voucher

curl --location 'https://www.headout.com/api/public/v2/bookings/126890/vouchers/415872/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

{
  "bookingStatus": "COMPLETED",
  "voucherTemplate": "SINGLE_PAGE",
  "header": {
    "bookingId": 126890,
    "voucherId": 415872,
    "displayBookingId": "HO-126890",
    "product": {
      "productId": 18969,
      "name": "Skip-the-Line: Colosseum, Roman Forum & Palatine Hill Ticket"
    },
    "variant": {
      "variantId": 25525,
      "name": "Guided Tour — Small Group"
    },
    "vendorLogoUrl": "https://cdn.headout.com/vendor/logos/opera-tours.png"
  },
  "callouts": [
    {
      "title": "Important information",
      "htmlDescription": "<p>Meet your host at the designated meeting point. Do check the location instructions to get there.</p>"
    }
  ],
  "bookingDetails": {
    "purchaseDateTime": "2026-05-10T14:32:00",
    "customerName": "Jane Smith",
    "paxSummary": {
      "summary": "2 Adults, 1 Child",
      "details": [
        {
          "paxType": "ADULT",
          "displayName": "Adult",
          "count": 2,
          "totalPrice": null
        },
        {
          "paxType": "CHILD",
          "displayName": "Child",
          "count": 1,
          "totalPrice": null
        }
      ]
    },
    "guestFields": [
      {
        "guestNumber": 1,
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "phone": "+393331234567",
        "customFields": null
      }
    ],
    "seats": null,
    "schedule": {
      "openDated": false,
      "experienceDate": "2026-06-15",
      "voucherValidUntil": null,
      "experienceStartDateTime": "2026-06-15T09:00:00",
      "experienceEndDateTime": "2026-06-15T12:00:00",
      "durationMinutes": 180,
      "inventoryType": "FIXED_START_FIXED_DURATION"
    },
    "tourProperties": [
      {
        "type": "Language",
        "values": ["English"]
      }
    ],
    "pickupDropoffLocation": null
  },
  "checkinButton": null,
  "ticketSection": {
    "heading": "Your tickets",
    "subheading": "Download & show tickets at the venue",
    "tickets": [
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-1.pdf",
        "ticketCode": "TKT-9F21A",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 1"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-2.pdf",
        "ticketCode": "TKT-9F21B",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 2"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-3.pdf",
        "ticketCode": "TKT-9F21C",
        "ticketName": "Child Ticket",
        "actionCta": "Download ticket Child Ticket 3"
      }
    ]
  },
  "instructions": {
    "legacy": null,
    "structured": {
      "generalInstructions": {
        "title": "General Instructions",
        "hasLateArrivalPolicy": false,
        "photoIdRequired": true,
        "reportingTimes": [
          {
            "label": "Arrive early",
            "value": "Don't miss a moment, arrive 15 minutes early to make the most out of your experience."
          }
        ]
      },
      "location": {
        "title": "Where to go?",
        "heading": "Head to this location to start your experience",
        "addressSequenceType": "SINGLE_ADDRESS",
        "voucherExchangeLocationType": "VENUE_LOCATION",
        "addressGroups": [
          [
            {
              "badgeLabel": "Address details",
              "addressLine1": "Arch of Titus",
              "addressLine2": null,
              "city": "Rome",
              "country": "Italy",
              "zip": "00186",
              "landmark": "Near the Colosseum main entrance",
              "googleMapLink": "https://maps.google.com/?q=41.8902,12.4924",
              "latitude": 41.8902,
              "longitude": 12.4924,
              "hostDetails": "Look for your guide holding a green Opera Tours sign",
              "mediaLinks": null
            }
          ]
        ]
      },
      "additionalInfo": null,
      "policies": [
        {
          "type": "BOOKING_AMENDMENT",
          "value": "<p>Free cancellation up to 24 hours before the experience start time.</p>"
        }
      ]
    }
  },
  "partnerDetails": {
    "vendorName": "XX Tours YY",
    "contactNumbers": ["+00 00 0000 0000"],
    "referenceNumbers": ["XXYY-0000-000000"]
  },
  "disclaimer": "Please carry a valid government-issued photo ID. Children under 6 enter free but must be accompanied by an adult."
}

GET

api

public

bookings

{bookingId}

vouchers

{voucherId}

curl --location 'https://www.headout.com/api/public/v2/bookings/126890/vouchers/415872/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

{
  "bookingStatus": "COMPLETED",
  "voucherTemplate": "SINGLE_PAGE",
  "header": {
    "bookingId": 126890,
    "voucherId": 415872,
    "displayBookingId": "HO-126890",
    "product": {
      "productId": 18969,
      "name": "Skip-the-Line: Colosseum, Roman Forum & Palatine Hill Ticket"
    },
    "variant": {
      "variantId": 25525,
      "name": "Guided Tour — Small Group"
    },
    "vendorLogoUrl": "https://cdn.headout.com/vendor/logos/opera-tours.png"
  },
  "callouts": [
    {
      "title": "Important information",
      "htmlDescription": "<p>Meet your host at the designated meeting point. Do check the location instructions to get there.</p>"
    }
  ],
  "bookingDetails": {
    "purchaseDateTime": "2026-05-10T14:32:00",
    "customerName": "Jane Smith",
    "paxSummary": {
      "summary": "2 Adults, 1 Child",
      "details": [
        {
          "paxType": "ADULT",
          "displayName": "Adult",
          "count": 2,
          "totalPrice": null
        },
        {
          "paxType": "CHILD",
          "displayName": "Child",
          "count": 1,
          "totalPrice": null
        }
      ]
    },
    "guestFields": [
      {
        "guestNumber": 1,
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "phone": "+393331234567",
        "customFields": null
      }
    ],
    "seats": null,
    "schedule": {
      "openDated": false,
      "experienceDate": "2026-06-15",
      "voucherValidUntil": null,
      "experienceStartDateTime": "2026-06-15T09:00:00",
      "experienceEndDateTime": "2026-06-15T12:00:00",
      "durationMinutes": 180,
      "inventoryType": "FIXED_START_FIXED_DURATION"
    },
    "tourProperties": [
      {
        "type": "Language",
        "values": ["English"]
      }
    ],
    "pickupDropoffLocation": null
  },
  "checkinButton": null,
  "ticketSection": {
    "heading": "Your tickets",
    "subheading": "Download & show tickets at the venue",
    "tickets": [
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-1.pdf",
        "ticketCode": "TKT-9F21A",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 1"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-2.pdf",
        "ticketCode": "TKT-9F21B",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 2"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-3.pdf",
        "ticketCode": "TKT-9F21C",
        "ticketName": "Child Ticket",
        "actionCta": "Download ticket Child Ticket 3"
      }
    ]
  },
  "instructions": {
    "legacy": null,
    "structured": {
      "generalInstructions": {
        "title": "General Instructions",
        "hasLateArrivalPolicy": false,
        "photoIdRequired": true,
        "reportingTimes": [
          {
            "label": "Arrive early",
            "value": "Don't miss a moment, arrive 15 minutes early to make the most out of your experience."
          }
        ]
      },
      "location": {
        "title": "Where to go?",
        "heading": "Head to this location to start your experience",
        "addressSequenceType": "SINGLE_ADDRESS",
        "voucherExchangeLocationType": "VENUE_LOCATION",
        "addressGroups": [
          [
            {
              "badgeLabel": "Address details",
              "addressLine1": "Arch of Titus",
              "addressLine2": null,
              "city": "Rome",
              "country": "Italy",
              "zip": "00186",
              "landmark": "Near the Colosseum main entrance",
              "googleMapLink": "https://maps.google.com/?q=41.8902,12.4924",
              "latitude": 41.8902,
              "longitude": 12.4924,
              "hostDetails": "Look for your guide holding a green Opera Tours sign",
              "mediaLinks": null
            }
          ]
        ]
      },
      "additionalInfo": null,
      "policies": [
        {
          "type": "BOOKING_AMENDMENT",
          "value": "<p>Free cancellation up to 24 hours before the experience start time.</p>"
        }
      ]
    }
  },
  "partnerDetails": {
    "vendorName": "XX Tours YY",
    "contactNumbers": ["+00 00 0000 0000"],
    "referenceNumbers": ["XXYY-0000-000000"]
  },
  "disclaimer": "Please carry a valid government-issued photo ID. Children under 6 enter free but must be accompanied by an adult."
}

Returns everything you need to show a customer their booking confirmation: the booking and product it was made against, who is travelling and when, where to go, the tickets themselves, and any information the operator wants displayed. Both ids in the URL come straight off the create, list, and get booking responses: {bookingId} is that response’s bookingId, and {voucherId} is its voucherId. For a walkthrough of every section and field — what each one holds, when it is null, and how it renders on the voucher — see Voucher API deep dive, under Key concepts in the Guides.

curl --location 'https://www.headout.com/api/public/v2/bookings/126890/vouchers/415872/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

{
  "bookingStatus": "COMPLETED",
  "voucherTemplate": "SINGLE_PAGE",
  "header": {
    "bookingId": 126890,
    "voucherId": 415872,
    "displayBookingId": "HO-126890",
    "product": {
      "productId": 18969,
      "name": "Skip-the-Line: Colosseum, Roman Forum & Palatine Hill Ticket"
    },
    "variant": {
      "variantId": 25525,
      "name": "Guided Tour — Small Group"
    },
    "vendorLogoUrl": "https://cdn.headout.com/vendor/logos/opera-tours.png"
  },
  "callouts": [
    {
      "title": "Important information",
      "htmlDescription": "<p>Meet your host at the designated meeting point. Do check the location instructions to get there.</p>"
    }
  ],
  "bookingDetails": {
    "purchaseDateTime": "2026-05-10T14:32:00",
    "customerName": "Jane Smith",
    "paxSummary": {
      "summary": "2 Adults, 1 Child",
      "details": [
        {
          "paxType": "ADULT",
          "displayName": "Adult",
          "count": 2,
          "totalPrice": null
        },
        {
          "paxType": "CHILD",
          "displayName": "Child",
          "count": 1,
          "totalPrice": null
        }
      ]
    },
    "guestFields": [
      {
        "guestNumber": 1,
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "phone": "+393331234567",
        "customFields": null
      }
    ],
    "seats": null,
    "schedule": {
      "openDated": false,
      "experienceDate": "2026-06-15",
      "voucherValidUntil": null,
      "experienceStartDateTime": "2026-06-15T09:00:00",
      "experienceEndDateTime": "2026-06-15T12:00:00",
      "durationMinutes": 180,
      "inventoryType": "FIXED_START_FIXED_DURATION"
    },
    "tourProperties": [
      {
        "type": "Language",
        "values": ["English"]
      }
    ],
    "pickupDropoffLocation": null
  },
  "checkinButton": null,
  "ticketSection": {
    "heading": "Your tickets",
    "subheading": "Download & show tickets at the venue",
    "tickets": [
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-1.pdf",
        "ticketCode": "TKT-9F21A",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 1"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-2.pdf",
        "ticketCode": "TKT-9F21B",
        "ticketName": "Adult Ticket",
        "actionCta": "Download ticket Adult Ticket 2"
      },
      {
        "ticketType": "PDF_URL",
        "displayType": "PDF",
        "url": "https://www.example.com/example-voucher-3.pdf",
        "ticketCode": "TKT-9F21C",
        "ticketName": "Child Ticket",
        "actionCta": "Download ticket Child Ticket 3"
      }
    ]
  },
  "instructions": {
    "legacy": null,
    "structured": {
      "generalInstructions": {
        "title": "General Instructions",
        "hasLateArrivalPolicy": false,
        "photoIdRequired": true,
        "reportingTimes": [
          {
            "label": "Arrive early",
            "value": "Don't miss a moment, arrive 15 minutes early to make the most out of your experience."
          }
        ]
      },
      "location": {
        "title": "Where to go?",
        "heading": "Head to this location to start your experience",
        "addressSequenceType": "SINGLE_ADDRESS",
        "voucherExchangeLocationType": "VENUE_LOCATION",
        "addressGroups": [
          [
            {
              "badgeLabel": "Address details",
              "addressLine1": "Arch of Titus",
              "addressLine2": null,
              "city": "Rome",
              "country": "Italy",
              "zip": "00186",
              "landmark": "Near the Colosseum main entrance",
              "googleMapLink": "https://maps.google.com/?q=41.8902,12.4924",
              "latitude": 41.8902,
              "longitude": 12.4924,
              "hostDetails": "Look for your guide holding a green Opera Tours sign",
              "mediaLinks": null
            }
          ]
        ]
      },
      "additionalInfo": null,
      "policies": [
        {
          "type": "BOOKING_AMENDMENT",
          "value": "<p>Free cancellation up to 24 hours before the experience start time.</p>"
        }
      ]
    }
  },
  "partnerDetails": {
    "vendorName": "XX Tours YY",
    "contactNumbers": ["+00 00 0000 0000"],
    "referenceNumbers": ["XXYY-0000-000000"]
  },
  "disclaimer": "Please carry a valid government-issued photo ID. Children under 6 enter free but must be accompanied by an adult."
}

Authorizations

Headout-Auth

string

header

required

Path Parameters

bookingId

integer

required

The booking the voucher belongs to. Use the bookingId returned in the booking response from the create, list, or get booking endpoints.

voucherId

integer

required

The voucher ID to retrieve. Use the voucherId returned in the booking response from the create, list, or get booking endpoints.

Response

Successful response

Full partner voucher payload for a confirmed booking.

bookingStatus

enum<string>

Current lifecycle state of the booking, using the same vocabulary as Get Booking. See Voucher booking status.

PENDING: Payment captured — confirmed with supplier.
COMPLETED: Booking fulfilled.
CANCELLED: Booking cancelled.

ticketSection and checkinButton are null for a cancelled booking, and ticketSection is usually null until the booking reaches COMPLETED. Bookings that were never captured (UNCAPTURED, CAPTURE_TIMEDOUT) have no voucher and return 404.

Available options:

PENDING,

COMPLETED,

CANCELLED

voucherTemplate

enum<string>

The layout this voucher is meant to be rendered in — SINGLE_PAGE for a single screen, MULTI_PAGE for a longer multi-section layout. Follow it: venue staff check vouchers against the expected layout, and rendering in a different one risks the guest being turned away. See Voucher template.

Available options:

SINGLE_PAGE,

MULTI_PAGE

header

object

Booking identifiers and product summary. Always returned, for every booking status.

Show child attributes

callouts

object[]

Ordered array of information banners to display on the voucher. Render every entry in the order returned, showing title as a heading and htmlDescription as its body — the HTML is pre-sanitized. Returned empty when the booking has no callouts.

Show child attributes

bookingDetails

object | null

Guest, schedule, seats, and location details. Null when no booking details are available for this voucher.

Show child attributes

checkinButton

object | null

Check-in URL when the experience supports online check-in. Null for most bookings, and always null for a cancelled booking.

Show child attributes

ticketSection

object | null

Downloadable tickets and QR codes. Null when no tickets are attached to the booking. The guest then follows the redemption instructions: if they include steps to generate or collect tickets, the guest must complete them; if not, no ticket is required and the guest presents the voucher at the venue. Also null for a cancelled booking. See a live example of a voucher with no ticket section.

Show child attributes

instructions

object | null

Redemption instructions. Null when no instructions exist. Exactly one of legacy or structured is non-null — branch on which field is present. See Voucher API deep dive.

Show child attributes

partnerDetails

object | null

Vendor/operator contact details. Null when the operator has not provided contact information.

Show child attributes

disclaimer

string | null

Legal disclaimer text to display at the bottom of the voucher. Null when not applicable.

Guide

Cities

Collections

Categories

Subcategories

Products

Availabilities

Inventory

Inventory Validate

Venue

Bookings

Vouchers

Manage webhook configuration (booking-status only — legacy)

Webhooks

Manage event subscriptions

Event Subscriptions

Authorizations

Path Parameters

Response