> ## 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. # Get a voucher > Retrieve the full partner voucher payload for a booking. Use the `bookingId` and `voucherId` returned in the booking response from the create, list, or get booking endpoints. 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](https://partner.headout.com/docs/api-partner/v2/vouchers/understanding-the-response.md), under **Key concepts** in the Guides. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --location 'https://www.headout.com/api/public/v2/bookings/126890/vouchers/415872/' \ --header 'Headout-Auth: ' ``` ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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": "

Meet your host at the designated meeting point. Do check the location instructions to get there.

" } ], "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": "

Free cancellation up to 24 hours before the experience start time.

" } ] } }, "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." } ``` ## OpenAPI ````yaml GET /api/public/v2/bookings/{bookingId}/vouchers/{voucherId}/ openapi: 3.1.0 info: title: Headout API Docs - API Partner v2 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/v2/bookings/{bookingId}/vouchers/{voucherId}/: get: tags: - Vouchers summary: Get a voucher operationId: v2GetVoucher parameters: - name: bookingId in: path required: true schema: type: integer description: >- The booking the voucher belongs to. Use the `bookingId` returned in the booking response from the create, list, or get booking endpoints. - name: voucherId in: path required: true schema: type: integer description: >- The voucher ID to retrieve. Use the `voucherId` returned in the booking response from the create, list, or get booking endpoints. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/V2Voucher' '401': description: Missing or invalid `Headout-Auth` '403': description: >- Partner not active, not an API Partner, or the `bookingId` does not exist or is not owned by this partner '404': description: >- No voucher available for this booking, or the `voucherId` does not belong to the given `bookingId` security: - apiKeyAuth: [] components: schemas: V2Voucher: type: object description: Full partner voucher payload for a confirmed booking. properties: bookingStatus: type: string enum: - PENDING - COMPLETED - CANCELLED description: > Current lifecycle state of the booking, using the same vocabulary as [Get Booking](/api-partner/v2/bookings/get). See [Voucher booking status](/guide/enums-and-error-codes#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`. voucherTemplate: type: string enum: - SINGLE_PAGE - MULTI_PAGE description: >- 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](/guide/enums-and-error-codes#voucher-template). header: $ref: '#/components/schemas/V2VoucherHeader' description: >- Booking identifiers and product summary. Always returned, for every booking status. callouts: type: array description: >- 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. items: $ref: '#/components/schemas/V2VoucherCallout' bookingDetails: description: >- Guest, schedule, seats, and location details. Null when no booking details are available for this voucher. oneOf: - $ref: '#/components/schemas/V2VoucherBookingDetails' - type: 'null' checkinButton: description: >- Check-in URL when the experience supports online check-in. Null for most bookings, and always null for a cancelled booking. oneOf: - $ref: '#/components/schemas/V2VoucherCheckinButton' - type: 'null' ticketSection: description: >- 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](https://www.sandbox-headout.com/voucher/1000003695/?secureBookingId=KniayC4xc5askqFYywK2TwRpDwHq7L53XorHacODZGnuyJOrzZ1pv7V3VN7JbqqZf06hTP3xzUD3MQid_TbP7kRCsjjqpfJBeBxlbqWQknc%3D&source=internal) of a voucher with no ticket section. oneOf: - $ref: '#/components/schemas/V2VoucherTicketSection' - type: 'null' instructions: description: >- 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](/api-partner/v2/vouchers/understanding-the-response#instructions). oneOf: - $ref: '#/components/schemas/V2VoucherInstructions' - type: 'null' partnerDetails: description: >- Vendor/operator contact details. Null when the operator has not provided contact information. oneOf: - $ref: '#/components/schemas/V2VoucherPartnerDetails' - type: 'null' disclaimer: type: - string - 'null' description: >- Legal disclaimer text to display at the bottom of the voucher. Null when not applicable. V2VoucherHeader: type: object description: Booking identifiers and product summary. properties: bookingId: type: integer description: >- Headout's identifier for the booking — the same value as `bookingId` on [Get Booking](/api-partner/v2/bookings/get). voucherId: type: integer description: >- The voucher ID. Matches the `{voucherId}` you passed in the request URL. displayBookingId: type: - string - 'null' description: >- Booking reference to show the guest on the voucher. If it is ever absent, display `voucherId` in its place so a reference is always shown. product: type: object description: Product/experience summary. properties: productId: type: - integer - 'null' description: Headout product ID. name: type: string description: Display name of the experience. variant: description: Variant (tour option) summary. oneOf: - type: object properties: variantId: type: - integer - 'null' description: Headout variant ID. name: type: - string - 'null' description: Display name of the variant. - type: 'null' vendorLogoUrl: type: - string - 'null' description: >- Vendor logo to show on the voucher. Null when the vendor does not want their logo on it — render the voucher without a logo rather than substituting your own or a placeholder. V2VoucherCallout: type: object description: >- Redemption callout banner. Display `title` as a heading and render `htmlDescription` directly — it is pre-sanitized HTML. required: - title - htmlDescription properties: title: type: string description: Callout heading — display as-is. htmlDescription: type: string description: Pre-sanitized HTML body of the callout. Render directly. V2VoucherBookingDetails: type: object description: Guest, schedule, seat, and location details for the booking. properties: purchaseDateTime: type: string format: date-time description: >- Date-time when the booking was made, in local time, no timezone offset (format `yyyy-MM-dd'T'HH:mm:ss`). e.g. `2026-05-10T14:32:00`. See [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). customerName: type: string description: Primary guest name as entered at checkout. paxSummary: description: >- Guest count summary. Null when no guest breakdown is available for the booking. oneOf: - type: object properties: summary: type: string description: Human-readable guest count (e.g. `"2 Adults, 1 Child"`). details: type: array description: Per-guest-type breakdown. items: type: object properties: paxType: type: string description: >- Pax type (e.g. `ADULT`, `CHILD`, `INFANT`). See [Person types](/guide/enums-and-error-codes#person-types). displayName: type: string description: Display name for this pax type. count: type: integer description: Number of guests of this type. totalPrice: description: >- Total price for all guests of this type, in the same `{amount, currencyCode}` shape as `price` on the booking endpoints. Not available for every experience, so treat it as optional. oneOf: - type: object properties: amount: type: number format: double description: Price amount for all guests of this type. currencyCode: type: string description: >- Currency code for the amount. See [Currency Codes](/guide/enums-and-error-codes#currency-codes). - type: 'null' - type: 'null' guestFields: description: >- Per-guest form data collected at checkout. Null when the experience does not collect per-guest fields. oneOf: - type: array items: type: object properties: guestNumber: type: integer description: 1-based guest index. name: type: - string - 'null' description: Guest name. email: type: - string - 'null' description: Guest email. phone: type: - string - 'null' description: Guest phone number. customFields: description: >- Experience-specific fields (dietary preference, t-shirt size, etc.). Null when no custom fields were collected. oneOf: - type: array items: type: object properties: label: type: string description: Field label. value: type: string description: Value entered by the guest. - type: 'null' - type: 'null' seats: description: Allocated seat information. Null for non-seatmap bookings. oneOf: - type: object properties: summary: type: string description: Human-readable seat allocation summary. details: type: array items: type: object properties: sectionName: type: string description: Seating section name. seats: type: array items: type: object properties: row: type: string seatNumber: type: string seatCode: type: string description: type: - string - 'null' description: Seat notes (e.g. `"Wheelchair Accessible"`). - type: 'null' schedule: type: object description: Experience date and time details. properties: openDated: type: boolean description: >- When true, no specific date is fixed — the guest chooses later. Date/time fields will be null; use `voucherValidUntil` for the redemption deadline. experienceDate: type: - string - 'null' format: date description: >- Scheduled experience date (format `yyyy-MM-dd`). Null when the booking has no fixed date. voucherValidUntil: type: - string - 'null' format: date-time description: >- Voucher redemption deadline, in local time, no timezone offset (format `yyyy-MM-dd'T'HH:mm:ss`). This is the relevant expiry for open-dated bookings. Null when the voucher has no deadline. experienceStartDateTime: type: - string - 'null' format: date-time description: >- Combined `experienceDate` + start time, in local time, no timezone offset (format `yyyy-MM-dd'T'HH:mm:ss`). Null when there is no fixed date or no start time. experienceEndDateTime: type: - string - 'null' format: date-time description: >- Combined `experienceDate` + end time, in local time, no timezone offset (format `yyyy-MM-dd'T'HH:mm:ss`). Null when there is no fixed date or no end time. durationMinutes: type: - integer - 'null' description: >- Experience duration in minutes. Null when duration is not defined. inventoryType: type: string enum: - FIXED_START_FIXED_DURATION - FLEXIBLE_START_FIXED_DURATION - FIXED_START_FLEXIBLE_DURATION - FLEXIBLE_START_FLEXIBLE_DURATION description: >- How the experience schedule is structured. See [Inventory types](/guide/enums-and-error-codes#inventory-types). tourProperties: description: >- Tour options selected at booking (language, group size, activity level, etc.), each with a `label` and `values[]`. Language property appears first when present. Null when no properties were selected. oneOf: - type: array items: type: object properties: type: type: string description: Property name (e.g. `"Language"`, `"Group Size"`). values: type: array items: type: string description: Selected values. - type: 'null' pickupDropoffLocation: description: >- Where the guest is collected, and dropped off, for this booking. Null when the booking has no pickup. A meeting point is not returned here — it lives on `instructions.legacy.location`. oneOf: - $ref: '#/components/schemas/V2VoucherLocation' - type: 'null' V2VoucherCheckinButton: type: object description: Online check-in link for experiences that support it. properties: checkinUrl: type: string description: URL the customer can visit to check in. V2VoucherTicketSection: type: object description: Downloadable tickets and QR/barcode codes. properties: heading: type: string description: Ready-to-render section heading (e.g. `"Your tickets"`). subheading: type: - string - 'null' description: >- Ready-to-render supporting line (e.g. `"Download and show this ticket at the venue"`). Null when the section has none. tickets: type: array description: >- List of ticket items. Can hold more tickets than the booking has guests, and can mix ticket types. Render every item; each one is needed at the venue. items: type: object properties: ticketType: type: string enum: - PDF_URL - HTML_URL - QRCODE - BARCODE - TEXT description: >- Underlying ticket format. See [Ticket type](/guide/enums-and-error-codes#ticket-types). displayType: type: string enum: - IMAGE - TICKET_NUMBER - PDF - NONE description: > How to render this ticket. See [Ticket display type](/guide/enums-and-error-codes#ticket-display-type). - `PDF`: show a download button; use `actionCta` as the button label and `url` as the download link. - `IMAGE`: render `url` as a QR code or barcode image. - `TICKET_NUMBER`: display `ticketCode` as a text confirmation code. - `NONE`: do not render (unrecognized format). url: type: - string - 'null' description: >- Download or display URL. For `QRCODE` and `BARCODE`, a JPEG image of the scannable code. Null for `TEXT`, where `ticketCode` holds the code. ticketCode: type: - string - 'null' description: >- Reference code for this ticket, carried for every ticket type. Display it as the confirmation code when `displayType` is `TICKET_NUMBER`. Null when the ticket has no code. ticketName: type: - string - 'null' description: Descriptive name for this ticket entry. actionCta: type: - string - 'null' description: >- Action-button label, returned only for tickets with `displayType: PDF` (e.g. `"Download ticket Adult 1"`). Null for every other display type. V2VoucherInstructions: type: object description: > Redemption instructions. Exactly one of `legacy` or `structured` is non-null — branch on which is present. See [Voucher API deep dive](/api-partner/v2/vouchers/understanding-the-response#instructions). properties: legacy: description: >- Vendor-authored instructions for experiences not yet on the structured model. Null when `structured` is returned instead. oneOf: - type: object properties: htmlContent: type: - string - 'null' description: >- Pre-sanitized HTML fragment. Null when the experience has a meeting point but no instruction content. location: description: >- The meeting point these instructions belong to. Null when the experience has no meeting point. oneOf: - $ref: '#/components/schemas/V2VoucherLocation' - type: 'null' - type: 'null' structured: description: >- Structured instruction sections. Returned for experiences with structured redemption instructions; `htmlContent` will be null. oneOf: - $ref: '#/components/schemas/V2VoucherStructuredInstructions' - type: 'null' V2VoucherPartnerDetails: type: object description: Vendor/operator contact information. properties: vendorName: type: string description: Operator or vendor name. contactNumbers: description: Phone numbers for the operator. Null when not provided. oneOf: - type: array items: type: string - type: 'null' referenceNumbers: description: Operator booking reference numbers. Null when not provided. oneOf: - type: array items: type: string - type: 'null' V2VoucherLocation: type: object description: >- A single physical location on the voucher. The pickup-only fields (`pickupTime`, `importantNotes`, `pickupDropOffType`, `dropoff`) are null wherever the location is a meeting point. properties: address: type: - string - 'null' description: Free-text address or description. Null when not available. directionsUrl: type: - string - 'null' description: Google Maps link. Null when no coordinates are available. coordinates: description: Lat/lng coordinates. Null when not available. oneOf: - type: object properties: latitude: type: number longitude: type: number - type: 'null' pickupTime: type: - string - 'null' description: >- Ready-to-render pickup sentence (e.g. `"You will be picked up between 08:30 - 09:00"`). Null for meeting points and when no pickup timing is configured. importantNotes: description: Array of pickup notes. Null when none. oneOf: - type: array items: type: string - type: 'null' pickupDropOffType: type: - string - 'null' enum: - PICKUP - PICKUP_AND_DROPOFF - PICKUP_SAME_AS_DROPOFF - null description: >- For transfer experiences, whether the booking includes a drop-off as well as a pickup. Null when the experience is not a transfer. See [Pickup drop-off type](/guide/enums-and-error-codes#pickup-drop-off-type). dropoff: description: >- Where the guest is dropped off at the end of a transfer. Null when the booking has no drop-off. oneOf: - type: object properties: address: type: - string - 'null' description: >- Free-text drop-off address or description. Null when not available. directionsUrl: type: - string - 'null' description: >- Google Maps link for the drop-off. Null when no coordinates are available. coordinates: description: Lat/lng of the drop-off. Null when not available. oneOf: - type: object properties: latitude: type: number longitude: type: number - type: 'null' importantNotes: description: Array of drop-off notes. Null when none. oneOf: - type: array items: type: string - type: 'null' - type: 'null' V2VoucherStructuredInstructions: type: object properties: generalInstructions: description: Late arrival policy, photo ID requirement, and reporting times. oneOf: - type: object properties: title: type: string description: Section title. hasLateArrivalPolicy: type: boolean description: >- When true, a late-arrival policy applies — latecomers may be refused entry and are not eligible for a refund. Surface this as a warning. photoIdRequired: type: boolean description: >- Whether guests must bring a valid government-issued photo ID. reportingTimes: description: >- Arrival guidance, ready to render. Null when no reporting time is configured. oneOf: - type: array items: type: object properties: label: type: string description: >- Label for the arrival prompt (e.g. `"Arrive early"`). value: type: string description: >- Pre-formatted sentence (e.g. `"Don't miss a moment, arrive 15 minutes early to make the most out of your experience."`). - type: 'null' - type: 'null' location: description: >- Address groups with sequence-aware structure. See [Voucher API deep dive](/api-partner/v2/vouchers/understanding-the-response#address-group-shapes). oneOf: - $ref: '#/components/schemas/V2VoucherStructuredLocation' - type: 'null' additionalInfo: description: >- Extra operator-supplied information for this experience. Null when the operator has not provided any. oneOf: - type: object properties: title: type: string description: Section title. htmlContent: type: string description: Pre-sanitized HTML content. - type: 'null' policies: description: >- Booking policies, one entry per policy. Null when the experience has none. oneOf: - type: array items: type: object properties: type: type: string enum: - BOOKING_AMENDMENT description: >- What the policy covers. See [Policy type](/guide/enums-and-error-codes#policy-type). value: type: string description: >- Policy text as pre-sanitized HTML. Render it under a heading of your own. - type: 'null' V2VoucherStructuredLocation: type: object description: > Address groups for the redemption location. `addressGroups` is an array of address arrays whose shape depends on `addressSequenceType`. See [Voucher API deep dive](/api-partner/v2/vouchers/understanding-the-response#address-group-shapes). properties: title: type: string description: Section title (e.g. `"Where to go?"`). heading: type: string description: >- Instruction sentence for the section (e.g. `"Head to this location to start your experience"`). Render it as supporting copy under `title`. addressSequenceType: type: - string - 'null' enum: - SINGLE_ADDRESS - ALL_ADDRESS_ANY_ORDER - ALL_ADDRESS_SPECIFIC_ORDER - null description: > Controls the shape of `addressGroups`. See [Address sequence type](/guide/enums-and-error-codes#address-sequence-type). - `SINGLE_ADDRESS` / `ALL_ADDRESS_ANY_ORDER`: one flat group holding all addresses. - `ALL_ADDRESS_SPECIFIC_ORDER` / null: one group per route, each a sequential itinerary. voucherExchangeLocationType: type: - string - 'null' enum: - VENUE_LOCATION - DIFF_LOCATION - null description: >- Whether the voucher is exchanged at the activity venue (`VENUE_LOCATION`) or at a different physical location (`DIFF_LOCATION`). Applies to the location section as a whole, not to individual addresses. Null when not configured. See [Voucher exchange location type](/guide/enums-and-error-codes#voucher-exchange-location-type). addressGroups: type: array description: >- Array of address arrays. Each inner array is one group (one route or one set of options). Addresses within a group carry position-aware `badgeLabel` values. items: type: array items: $ref: '#/components/schemas/V2VoucherAddress' V2VoucherAddress: type: object description: Individual address within a location group. properties: badgeLabel: type: string description: > Display label for this address, set per `addressSequenceType`: - `SINGLE_ADDRESS`: `"Option 1"`, `"Option 2"`, … - `ALL_ADDRESS_ANY_ORDER`: `"Location 1"`, `"Location 2"`, … - `ALL_ADDRESS_SPECIFIC_ORDER`: `"Start Location"` (first), `"End Location"` (last), `"Location N"` (middle). - null: `"Address details"` for all addresses. addressLine1: type: - string - 'null' description: Street address line 1. addressLine2: type: - string - 'null' description: Street address line 2. city: type: - string - 'null' country: type: - string - 'null' zip: type: - string - 'null' description: Postal code. landmark: type: - string - 'null' description: Nearby landmark text (e.g. `"Near the main fountain"`). googleMapLink: type: - string - 'null' description: Deep link to Google Maps for this address. latitude: type: - number - 'null' format: double longitude: type: - number - 'null' format: double hostDetails: type: - string - 'null' description: >- Host identifier text for meeting-point experiences (e.g. guide name or description of the flag they hold). mediaLinks: description: Photos or media of the location. Null when not provided. oneOf: - type: array items: type: string - type: 'null' securitySchemes: apiKeyAuth: type: apiKey in: header name: Headout-Auth ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.