> ## 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 product by ID
> We are soon moving to **v2 APIs** and **v1** will be deprecated. Switch to **v2** using the version selector above.
Retrieve full details for a single product by its ID, including all variants, pricing, images, content, location, and input fields required for booking. Optionally localize the response by specifying a language code and currency.
## OpenAPI
````yaml GET /api/public/v1/product/get/{productId}/
openapi: 3.1.0
info:
title: Headout API Docs
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/v1/product/get/{productId}/:
get:
tags:
- Products
summary: Get product by ID
description: >-
We are soon moving to **v2 APIs** and **v1** will be
deprecated. Switch to **v2** using the version selector above.
Retrieve full details for a single product by its ID, including all
variants, pricing, images, content, location, and input fields required
for booking. Optionally localize the response by specifying a language
code and currency.
operationId: v1GetProductById
parameters:
- name: productId
in: path
required: true
schema:
type: string
description: ID of the product to fetch.
- name: currencyCode
in: query
schema:
type: string
description: Currency code for product pricing.
- name: fetch-variants
in: query
schema:
type: boolean
required: false
description: Flag to fetch product variants.
- name: language
in: query
required: false
schema:
type: string
example: EN
default: EN
enum:
- EN
- ES
- FR
- IT
- DE
- PT
- NL
- PL
- KO
- JA
- ZH_HANS
- ZH_HANT
- AR
- DA
- 'NO'
- RO
- RU
- SV
- TR
description: >-
Language code for localization. Content falls back to English when a
translation is unavailable.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
example:
id: 19513
name: 'Edge Observation Deck Tickets: Timed Entry'
url: >-
/edge-observation-deck-tickets/tickets-to-edge-observation-deck-e-19513/
canonicalUrl: >-
https://www.headout.com/edge-observation-deck-tickets/tickets-to-edge-observation-deck-e-19513/
neighbourhood: ''
city:
name: New York
code: NEW_YORK
currency:
code: USD
name: United States Dollar
symbol: US$
localSymbol: $
precision: 2
displayTags: []
images:
- url: >-
https://cdn-imgix.headout.com/media/images/7dff2143faf0c49109d1aeca8a7dcd9f-19513-new-york-edge-observation-deck-adimssion-tickets--09.jpg
altText: >-
Visitors on Edge Observation Deck with New York City
skyline at sunset.
description: >-
Visitors on Edge Observation Deck with New York City
skyline at sunset.
credit: Edge
contentListHtml:
- title: Summary
type: SUMMARY_HTML
html: >-
Your experience
Take in New York City from
1,100 feet above Hudson Yards...
- title: Highlights
type: HIGHLIGHTS_HTML
html: >-
- Start your experience with a spectacular
multimedia journey...
- title: Inclusions
type: INCLUSIONS_HTML
html: - Timed entry to Edge Observation Deck
content:
- title: Summary
type: SUMMARY_HTML
html: >-
Your experience
Take in New York City from
1,100 feet above Hudson Yards...
startLocation:
geolocation:
latitude: 40.753395080566406
longitude: -74.00105285644531
address:
addressLine1: Edge
addressLine2: 30 Hudson Yards, New York, NY 10001, USA
cityName: NEW_YORK
postalCode: '10001'
state: ''
countryName: United States
endLocation:
geolocation:
latitude: 40.753395080566406
longitude: -74.00105285644531
address:
addressLine1: Edge
addressLine2: 30 Hudson Yards, New York, NY 10001, USA
cityName: NEW_YORK
postalCode: '10001'
state: ''
countryName: United States
productType: ATTRACTION
ratingCumulative:
avg: 4.5
count: 6252
hasInstantConfirmation: false
hasMobileTicket: true
variants:
- id: 38164
name: 'General Admission: Timed Entry'
description: '- Entry to Edge Observatory Deck at the time slot selected'
duration: 60000
inventoryType: FIXED_START_FLEXIBLE_DURATION
pax:
min: 1
max: 10
cashback:
value: 0
type: ABSOLUTE
ticketDeliveryInfoHtml: null
cancellationPolicy:
cancellable: true
cancellableUpTo: 1440
meetingPointInfo:
latitude: null
longitude: null
address: ''
inputFields:
- oldId: 119867
id: NAME
name: Full Name
dataType: STRING
validation:
regex: \s*[^\s]+\s+[^\s]+.*
minLength: 3
maxLength: 80
minValue: null
maxValue: null
required: true
values: null
level: PRIMARY_CUSTOMER
- oldId: 119868
id: EMAIL
name: Email
dataType: STRING
validation:
regex: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
minLength: 5
maxLength: null
minValue: null
maxValue: null
required: true
values: null
level: PRIMARY_CUSTOMER
- oldId: 119869
id: PHONE
name: Phone
dataType: STRING
validation:
regex: null
minLength: null
maxLength: 40
minValue: null
maxValue: null
required: true
values: null
level: PRIMARY_CUSTOMER
tags:
- OFFERS
- RECOMMENDED
- SCHEDULE-300-DAYS
properties: {}
propertiesV2: {}
pricing:
type: PER_PERSON
currencyCode: USD
minimumPrice:
originalPrice: 45.73
finalPrice: 45.73
bestDiscount: 0
inventorySelectionType: NORMAL
topReviews:
- title: null
customerName: Ellen Marie Pierce
reviewerImgUrl: null
rating: 5
content: >-
We saw this from our Hotel room and decided to visit. Oh
my goodness! The views were just outstanding!
reviewTime: 1773699952000
translatedContent: null
language: EN
security:
- apiKeyAuth: []
x-codeSamples:
- lang: curl
source: >
curl --location
'https://www.headout.com/api/public/v1/product/get/3336/?currencyCode=EUR&language=PT&fetch-variants=true'
\
--header 'Headout-Auth: '
components:
schemas:
Product:
type: object
properties:
id:
type: integer
description: >-
Headout's unique product identifier. Use this to fetch full product
details via the `getProductById` endpoint.
name:
type: string
description: >-
Display name of the experience (e.g., "Skip-the-Line Tickets to the
Eiffel Tower").
url:
type: string
description: Relative URL path for this product page on Headout.
canonicalUrl:
type: string
description: >-
The canonical Headout URL for this product page. Use for linking and
affiliate tracking.
neighbourhood:
type:
- string
- 'null'
description: >-
Neighbourhood or locality where the experience takes place (e.g.,
"Times Square", "Old Town").
content:
type:
- array
- 'null'
description: >-
Structured content sections for this product. Each item contains a
title, section type, and HTML content.
items:
type: object
properties:
title:
type: string
description: Section heading.
type:
type: string
description: >-
Content section type (e.g., `SUMMARY_HTML`, `HIGHLIGHTS_HTML`,
`INCLUSIONS_HTML`).
html:
type: string
description: HTML-formatted content for this section.
city:
type: object
description: The city where this experience takes place.
properties:
code:
type: string
description: >-
Uppercase city identifier used as a parameter in other API
endpoints (e.g., `NEW_YORK`, `DUBAI`, `LONDON`).
name:
type: string
description: Human-readable city name for display.
displayTags:
type: array
items:
type: string
description: >-
Display tags associated with the product (e.g., "Best Seller", "Top
Rated").
images:
type: array
items:
type: object
properties:
url:
type: string
description: >-
CDN URL for the image or video asset. Supports imgix query
parameters for resizing and format conversion.
altText:
type:
- string
- 'null'
description: Accessible alt text for the media asset.
description:
type:
- string
- 'null'
description: Descriptive text for the media asset.
credit:
type:
- string
- 'null'
description: Attribution or source credit for the media asset.
description: Product images for display in product detail pages.
startLocation:
type: object
description: >-
Meeting or departure point for this experience, including GPS
coordinates and optional address.
properties:
geolocation:
$ref: '#/components/schemas/Geolocation'
description: GPS coordinates of the meeting/departure point.
address:
type:
- object
- 'null'
description: Postal address of the meeting/departure point.
properties:
addressLine1:
type: string
description: Primary street address.
addressLine2:
type:
- string
- 'null'
description: Secondary address line (e.g., suite, floor).
cityName:
type: string
description: City name of the address.
postalCode:
type:
- string
- 'null'
description: Postal or ZIP code.
state:
type:
- string
- 'null'
description: State or province.
countryName:
type: string
description: Country name.
endLocation:
type:
- object
- 'null'
description: >-
Drop-off or end point for this experience. Same structure as
`startLocation`. Null if the experience ends at the start location.
properties:
geolocation:
$ref: '#/components/schemas/Geolocation'
description: GPS coordinates of the end/drop-off point.
address:
type:
- object
- 'null'
description: Postal address of the end point.
properties:
addressLine1:
type: string
addressLine2:
type:
- string
- 'null'
cityName:
type: string
postalCode:
type:
- string
- 'null'
state:
type:
- string
- 'null'
countryName:
type: string
productType:
type: string
enum:
- TOUR
- ACTIVITY
- EVENT
- ATTRACTION
- TRANSFER
- AIRPORT_TRANSFER
- ADD_ON
description: Experience category. Useful for filtering and display logic.
ratingCumulative:
$ref: '#/components/schemas/ReviewDetails'
description: Aggregated rating and review count from verified Headout customers.
pricing:
$ref: '#/components/schemas/ListingPrice'
description: >-
Starting price for display on product cards. Reflects the cheapest
available variant.
currency:
type: object
description: Currency in which all prices in this response are denominated.
properties:
code:
type: string
description: >-
Currency code (e.g., `USD`, `EUR`, `AED`). See [Currency
Codes](/guide/enums-and-error-codes#currency-codes).
name:
type: string
description: >-
Full name of the currency (e.g., "United States Dollar",
"Euro").
symbol:
type: string
description: International currency symbol (e.g., "US$", "EUR").
localSymbol:
type: string
description: >-
Locally preferred symbol for this currency (e.g., "$" for USD in
the US).
precision:
type: integer
description: >-
Number of decimal places used for this currency (e.g., 2 for
USD, 0 for JPY).
hasInstantConfirmation:
type: boolean
description: >-
Whether bookings for this product are confirmed immediately without
manual review.
hasMobileTicket:
type: boolean
description: >-
Whether this product supports mobile/digital tickets (no print
required).
inventorySelectionType:
type: string
enum:
- NORMAL
- SEATMAP
description: >-
Inventory selection flow for this product. Determines how date/time
selection should be presented to users.
variants:
type: array
items:
type: object
description: >-
A bookable option within the product (e.g., different seating
tiers, admission levels, or time slots).
properties:
id:
type: string
description: >-
Variant identifier. Use as `variantId` when fetching inventory
or creating a booking.
name:
type:
- string
- 'null'
description: >-
Display name of this variant option (e.g., "Rear Orchestra",
"Standard Admission"). Null or empty when the product has only
one variant — in that case the variant carries no special
distinguishing label.
description:
type:
- string
- 'null'
description: >-
Additional details about what distinguishes this variant from
others.
duration:
type:
- number
- 'null'
format: double
description: >-
Duration of the experience in milliseconds.
Null for `FIXED_START_FLEXIBLE_DURATION` and
`FLEXIBLE_START_FLEXIBLE_DURATION` inventory types, where the
duration is open-ended.
inventoryType:
type: string
enum:
- FIXED_START_FIXED_DURATION
- FIXED_START_FLEXIBLE_DURATION
- FLEXIBLE_START_FIXED_DURATION
- FLEXIBLE_START_FLEXIBLE_DURATION
description: >-
How inventory slots are structured for this variant. Affects
how `startDateTime` and `endDateTime` should be interpreted.
See [Inventory
Types](/guide/enums-and-error-codes#inventory-types).
- `FIXED_START_FIXED_DURATION`: Fixed entry time and fixed
duration (e.g., a Broadway show at 7 PM).
- `FIXED_START_FLEXIBLE_DURATION`: Fixed entry time, customer
stays as long as they wish (e.g., a timed-entry observation
deck).
- `FLEXIBLE_START_FIXED_DURATION`: Open-window entry, fixed
duration once started (e.g., a 1-hour balloon ride during a
morning window).
- `FLEXIBLE_START_FLEXIBLE_DURATION`: Open entry, open-ended
duration (e.g., a theme park day pass).
pax:
type: object
description: Allowed booking party size for this variant.
properties:
min:
type: integer
description: >-
Minimum number of people required per booking. 0 means no
minimum.
max:
type:
- integer
- 'null'
description: >-
Maximum number of people allowed per booking. Null means
no upper limit.
cashback:
type: object
description: Cashback incentive offered on bookings of this variant.
properties:
value:
type: number
format: double
description: >-
Cashback amount or percentage, depending on the type
field.
type:
type: string
enum:
- PERCENTAGE
- ABSOLUTE
description: How the cashback is calculated.
ticketDeliveryInfoHtml:
type:
- string
- 'null'
description: >-
HTML-formatted instructions on how tickets will be delivered
(e.g., email, mobile app, on-site collection).
inputFields:
type: array
items:
type: object
description: >-
A field that must be collected from the customer when
creating a booking for this variant.
properties:
oldId:
type: integer
description: >-
Legacy numeric field identifier for backwards
compatibility.
id:
type: string
description: >-
Field identifier used in the booking request (e.g.,
`NAME`, `EMAIL`, `PHONE`, or `CUSTOM_*`).
name:
type: string
description: >-
Human-readable label to display to the customer for this
field.
dataType:
type: string
enum:
- STRING
- ENUM
- BOOL
- INT
- FLOAT
- LOCATION
description: >-
Expected data type for this field's value. See [Input
Field Data
Types](/guide/enums-and-error-codes#input-field-data-types).
- `STRING`: free-form text — apply `regex`, `minLength`,
`maxLength` from `validation`.
- `ENUM`: one of the values in `validation.values` —
value must be an exact match.
- `BOOL`: boolean — submit as the string `"true"` or
`"false"`.
- `INT`: whole number — apply `minValue`, `maxValue`
from `validation`.
- `FLOAT`: decimal number — apply `minValue`, `maxValue`
from `validation`.
- `LOCATION`: pickup/drop-off location. If
`validation.values` is non-empty, items are **predefined
location objects** (see `PredefinedLocation` schema) —
render as a dropdown and submit the selected `id`. If
`validation.values` is null, accept a free-form address
string.
validation:
$ref: '#/components/schemas/FieldValidation'
description: >-
Constraints that must be satisfied when submitting a
value for this field.
level:
type: string
enum:
- PRIMARY_CUSTOMER
- ALL_CUSTOMER
description: >-
Who this field should be collected from. See [Input
Field
Level](/guide/enums-and-error-codes#input-field-level).
- `PRIMARY_CUSTOMER`: collect once from the lead guest
only (e.g., name, email, phone).
- `ALL_CUSTOMER`: collect from every guest in the
booking (e.g., weight, height, meal preference).
tags:
type: array
items:
type: string
description: >-
Internal classification tags for this variant (e.g.,
`BROADWAY`, `BTTFA`). Used for eligibility programs and
internal routing.
cancellationPolicy:
type:
- object
- 'null'
description: Cancellation terms for this variant.
properties:
cancellable:
type: boolean
description: Whether this variant supports cancellation.
cancellableUpTo:
type:
- integer
- 'null'
description: >-
Latest cancellation window in minutes before the
experience start time. Null means cancellation is allowed
up to the last moment.
meetingPointInfo:
type:
- object
- 'null'
description: Meeting or pick-up point details for this variant.
properties:
isPickupEnabled:
type: boolean
description: >-
Whether a hotel or address pickup service is available for
this variant.
servicePoints:
type: array
description: List of fixed pickup or meeting point locations.
items:
type: object
properties:
latitude:
type: number
format: double
description: Latitude of this service point.
longitude:
type: number
format: double
description: Longitude of this service point.
address:
type:
- string
- 'null'
description: Human-readable address of this service point.
properties:
type:
- object
- 'null'
description: >-
Additional variant-specific properties. Structure may vary by
product type.
contentListHtml:
type:
- array
- 'null'
description: >-
Structured content sections for this product in HTML format.
Complements the `content` field with pre-rendered HTML for rich
display.
items:
type: object
properties:
title:
type: string
description: Section heading.
type:
type: string
description: >-
Content section type (e.g., `INCLUSIONS`, `EXCLUSIONS`,
`GOOD_TO_KNOW`).
html:
type: string
description: HTML-formatted content for this section.
topReviews:
type:
- array
- 'null'
description: >-
Top customer reviews for this product. Useful for displaying social
proof on product pages.
items:
type: object
properties:
title:
type:
- string
- 'null'
description: Review headline or title.
customerName:
type: string
description: Display name of the reviewer.
reviewerImgUrl:
type:
- string
- 'null'
description: URL of the reviewer's profile image. Null if not available.
rating:
type: number
format: double
description: Numeric rating given by the reviewer (1–5 scale).
content:
type: string
description: Full review text.
reviewTime:
type: integer
format: int64
description: Review submission timestamp in milliseconds since Unix epoch.
translatedContent:
type:
- string
- 'null'
description: >-
Machine-translated review text in the requested language. Null
if not applicable.
language:
type: string
description: Original language of the review (e.g., `EN`, `ES`).
Geolocation:
type: object
properties:
latitude:
type: number
format: double
description: Latitude coordinate of the location in decimal degrees.
longitude:
type: number
format: double
description: Longitude coordinate of the location in decimal degrees.
ReviewDetails:
type: object
properties:
avg:
type: number
format: double
description: >-
Mean customer rating on a scale of 1-5, based on verified
post-experience reviews.
count:
type: integer
description: >-
Total number of verified customer ratings submitted for this
product.
ListingPrice:
type: object
properties:
type:
type: string
enum:
- PER_PERSON
- PER_GROUP
description: >-
Pricing model for this product. See [Listing Price
Types](/guide/enums-and-error-codes#listing-price-types).
- `PER_PERSON`: price per individual — inventory returns person
types (Adult, Child, etc.) each with their own price.
- `PER_GROUP`: single price for a group — inventory returns pricing
tiers by group size.
currencyCode:
type: string
description: >-
Currency code for all price values in this object. See [Currency
Codes](/guide/enums-and-error-codes#currency-codes).
minimumPrice:
$ref: '#/components/schemas/Price'
description: >-
Lowest available price across all variants and person types. Used as
the "from" price in listing displays.
bestDiscount:
type: number
format: double
description: >-
Highest discount percentage available across all variants, for
displaying promotional badges.
FieldValidation:
type: object
properties:
regex:
type:
- string
- 'null'
description: >-
Regular expression pattern the submitted value must match. Null when
not applicable (e.g., for non-string fields). Validate on the client
before submission to avoid booking errors.
minLength:
type:
- integer
- 'null'
description: >-
Minimum number of characters required. Null when not applicable
(e.g., for `INT`, `FLOAT`, `BOOL` fields).
maxLength:
type:
- integer
- 'null'
description: >-
Maximum number of characters allowed. Null when not applicable
(e.g., for `INT`, `FLOAT`, `BOOL` fields).
minValue:
type:
- number
- 'null'
format: double
description: >-
Minimum numeric value allowed. Null when not applicable (e.g., for
`STRING`, `BOOL` fields).
maxValue:
type:
- number
- 'null'
format: double
description: >-
Maximum numeric value allowed. Null when not applicable (e.g., for
`STRING`, `BOOL` fields).
required:
type: boolean
description: >-
Whether this field must be provided in the booking request. If true,
omitting it will cause the booking to fail.
values:
description: >-
Predefined allowed values for this field. The shape of items depends
on `inputFields.dataType`:
- **`ENUM`**: `string[]` — the submitted value must exactly match
one of these strings.
- **`LOCATION`** (predefined): array of location objects — render as
a dropdown and submit the selected `id` as the field value. See
`PredefinedLocation` schema.
- **All other types**: `null`.
oneOf:
- title: Enum Values
type: array
items:
type: string
description: String enum values (for `ENUM` dataType fields).
- title: Predefined Locations
type: array
items:
$ref: '#/components/schemas/PredefinedLocation'
description: >-
Predefined pickup/drop-off locations (for `LOCATION` dataType
fields with predefined options).
- type: 'null'
Price:
type: object
properties:
originalPrice:
type: number
format: double
description: >-
Full undiscounted price. Suitable for displaying as a strikethrough
price alongside the final price.
finalPrice:
type: number
format: double
description: >-
Actual price after applying any discounts or promotions. This is the
amount charged to the customer.
PredefinedLocation:
type: object
description: >-
A predefined pickup or drop-off location for a `LOCATION` dataType input
field.
When `validation.values` contains objects of this type, render them as a
dropdown.
Submit the selected location's `id` (as a string) as the input field
value when creating a booking.
properties:
id:
type: integer
description: >-
Unique identifier for this location. Submit this value as the input
field value when creating a booking.
latitude:
type: number
format: double
description: Latitude of the pickup/drop-off point in decimal degrees.
longitude:
type: number
format: double
description: Longitude of the pickup/drop-off point in decimal degrees.
address:
type: string
description: >-
Full street address of the location (e.g., "3600 S Las Vegas Blvd,
Las Vegas, NV 89109, USA").
displayName:
type: string
description: >-
Short human-readable label for display in a dropdown or list (e.g.,
"Bellagio").
timingConfig:
$ref: '#/components/schemas/LocationTimingConfig'
description: Optional pickup timing constraints for this location.
note:
type:
- object
- 'null'
description: >-
Additional instructions for this pickup location. Null if no note
exists.
properties:
content:
type:
- string
- 'null'
description: >-
The note text (e.g., "Meet at the main entrance, not the side
entrance.").
language:
type: string
description: Language code for the note content (e.g., `EN`, `ES`).
LocationTimingConfig:
type: object
description: >-
Pickup timing constraints for a predefined location. All fields are
nullable — null means no restriction applies.
properties:
startTime:
type:
- string
- 'null'
description: >-
Earliest allowed pickup time in HH:mm format (e.g., `10:30`). Null
if no earliest restriction.
endTime:
type:
- string
- 'null'
description: >-
Latest allowed pickup time in HH:mm format (e.g., `11:00`). Null if
no latest restriction.
minPeriod:
type:
- integer
- 'null'
description: >-
Minimum advance notice required for this pickup, in minutes. Null if
no minimum notice.
maxPeriod:
type:
- integer
- 'null'
description: >-
Maximum advance booking window for this pickup, in minutes. Null if
no maximum window.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Headout-Auth
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.