> ## 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.
# List bookings
Retrieve a paginated list of bookings attributed to your affiliate account within a given date range. Use this to reconcile earnings, audit attribution, and build your own reporting dashboard.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://www.headout.com/api/public/v2/affiliate/bookings/?startTime=2026-01-01T00%3A00%3A00Z&endTime=2026-12-31T23%3A59%3A59Z&offset=0&limit=20' \
--header 'Headout-Auth: '
```
```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"items": [
{
"bookingId": "32435721",
"status": "PENDING",
"creationTimestamp": 1782812820,
"startDateTime": "2026-07-15T10:00:00Z",
"numberOfGuests": 2,
"product": {
"id": "5246",
"name": "Madame Tussauds London — Advance Purchase",
"city": "London",
"country": "United Kingdom",
"variants": [
{
"id": "18432",
"name": "General Admission"
}
]
},
"price": {
"currencyCode": "GBP",
"amount": 34.13,
"amountUSD": 45.20,
"couponCode": null,
"couponDiscount": null,
"couponDiscountUSD": null
},
"commission": {
"partnerEarningsUSD": 4.57
},
"attribution": {
"attributionType": "WEB",
"utmSource": "newsletter",
"utmMedium": "email",
"utmCampaign": "summer-london"
},
"user": {
"language": "en",
"country": "GB",
"device": "WEB"
}
},
{
"bookingId": "32435722",
"status": "PENDING",
"creationTimestamp": 1782813480,
"startDateTime": "2026-07-20T09:00:00Z",
"numberOfGuests": 1,
"product": {
"id": "1866",
"name": "Burj Khalifa — Entry Tickets",
"city": "Dubai",
"country": "United Arab Emirates",
"variants": [
{
"id": "7821",
"name": "At the Top (124th & 125th Floor)"
}
]
},
"price": {
"currencyCode": "AED",
"amount": 189.00,
"amountUSD": 51.47,
"couponCode": null,
"couponDiscount": null,
"couponDiscountUSD": null
},
"commission": {
"partnerEarningsUSD": 5.20
},
"attribution": {
"attributionType": "WEB",
"utmSource": "blog",
"utmMedium": "organic",
"utmCampaign": "dubai-guide"
},
"user": {
"language": "en",
"country": "IN",
"device": "WEB"
}
},
{
"bookingId": "32435723",
"status": "COMPLETED",
"creationTimestamp": 1782814140,
"startDateTime": "2026-07-04T14:00:00Z",
"numberOfGuests": 3,
"product": {
"id": "700",
"name": "AMNH — Dated Entry",
"city": "New York",
"country": "United States",
"variants": [
{
"id": "2201",
"name": "General Admission"
}
]
},
"price": {
"currencyCode": "USD",
"amount": 37.00,
"amountUSD": 37.00,
"couponCode": "SUMMER10",
"couponDiscount": 3.70,
"couponDiscountUSD": 3.70
},
"commission": {
"partnerEarningsUSD": 3.70
},
"attribution": {
"attributionType": "WEB",
"utmSource": "instagram",
"utmMedium": "social",
"utmCampaign": "nyc-summer"
},
"user": {
"language": "en",
"country": "US",
"device": "APP"
}
}
],
"nextUrl": "/api/public/v2/affiliate/bookings/?startTime=2026-01-01T00%3A00%3A00Z&endTime=2026-12-31T23%3A59%3A59Z&offset=3&limit=3",
"prevUrl": null,
"total": 7,
"nextOffset": 3
}
```
## OpenAPI
````yaml specs/openapi-v2-affiliate.yaml GET /api/public/v2/affiliate/bookings/
openapi: 3.1.0
info:
title: Headout API Docs - Affiliate 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/affiliate/bookings/:
get:
tags:
- Bookings
summary: List bookings
operationId: v2AffiliateListBookings
parameters:
- name: startTime
in: query
required: true
schema:
type: string
format: date-time
description: Start of the date range (ISO 8601, e.g. `2026-01-01T00:00:00Z`).
- name: endTime
in: query
required: true
schema:
type: string
format: date-time
description: End of the date range (ISO 8601, e.g. `2026-12-31T23:59:59Z`).
- name: offset
in: query
required: false
schema:
type: integer
default: 0
description: Number of bookings to skip for pagination.
- name: limit
in: query
required: false
schema:
type: integer
default: 20
maximum: 100
description: Number of bookings to return per page. Maximum is 100.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateBookingPage'
'400':
description: >-
Missing or invalid parameters (startTime/endTime required, startTime
must be before endTime, offset/limit out of range)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 400
message:
type: string
example: startTime must be before endTime
'401':
description: Missing or invalid API key
'403':
description: API key is not an AFFILIATE type partner
security:
- apiKeyAuth: []
components:
schemas:
AffiliateBookingPage:
type: object
description: Paginated list of affiliate bookings.
properties:
items:
type: array
items:
$ref: '#/components/schemas/AffiliateBooking'
nextUrl:
type:
- string
- 'null'
description: URL for the next page of results. Null if this is the last page.
prevUrl:
type:
- string
- 'null'
description: >-
URL for the previous page of results. Null if this is the first
page.
total:
type: integer
description: Total number of bookings matching the query.
nextOffset:
type:
- integer
- 'null'
description: Offset to use for the next page. Null if this is the last page.
AffiliateBooking:
type: object
description: A single booking attributed to the affiliate.
properties:
bookingId:
type: string
description: >-
Unique booking identifier. Use this as the `{bookingId}` path
parameter in the Get Booking endpoint.
status:
type: string
enum:
- PENDING
- COMPLETED
- CANCELLED
description: >-
Current status of the booking. `CANCELLED` bookings have
`commission.partnerEarningsUSD` set to `0`.
creationTimestamp:
type: integer
format: int64
description: Unix epoch timestamp (seconds) when this booking was first created.
startDateTime:
type:
- string
- 'null'
format: date-time
description: >-
Scheduled start date and time of the experience (ISO 8601, UTC).
Null for open-dated products.
numberOfGuests:
type: integer
description: Total number of guests in the booking.
product:
$ref: '#/components/schemas/AffiliateBookingProduct'
price:
$ref: '#/components/schemas/AffiliateBookingPrice'
commission:
$ref: '#/components/schemas/AffiliateBookingCommission'
attribution:
$ref: '#/components/schemas/AffiliateBookingAttribution'
user:
$ref: '#/components/schemas/AffiliateBookingUser'
AffiliateBookingProduct:
type: object
description: Product information for the booking.
properties:
id:
type: string
description: Headout product (tour group) ID.
name:
type: string
description: Product name.
city:
type: string
description: City where the experience takes place.
country:
type: string
description: Country where the experience takes place.
variants:
type: array
description: Variant booked. Contains one entry.
items:
$ref: '#/components/schemas/AffiliateBookingVariant'
AffiliateBookingPrice:
type: object
description: Pricing details in the tour's local currency, plus USD equivalents.
properties:
currencyCode:
type: string
description: >-
ISO 4217 currency code for `amount` and `couponDiscount` (e.g.,
`USD`, `GBP`, `EUR`).
amount:
type: number
description: Amount paid by the customer in the tour's local currency.
amountUSD:
type: number
description: >-
Amount paid by the customer in USD, converted using the exchange
rate at the time of booking.
couponCode:
type:
- string
- 'null'
description: Coupon code applied to this booking, if any.
couponDiscount:
type:
- number
- 'null'
description: >-
Coupon discount amount in the tour's local currency. Null if no
coupon was applied.
couponDiscountUSD:
type:
- number
- 'null'
description: Coupon discount amount in USD. Null if no coupon was applied.
AffiliateBookingCommission:
type: object
description: Earnings for this booking in USD.
properties:
partnerEarningsUSD:
type: number
description: >
Your earnings for this booking in USD. Always `0` for `CANCELLED`
bookings. For `NET_PLUS` commercial model bookings, this is derived
from `partnerAmount` converted to USD using the exchange rate
captured at booking time.
AffiliateBookingAttribution:
type: object
description: Attribution details for this booking.
properties:
attributionType:
type: string
enum:
- WEB
- APP
- COUPON
description: >
How the booking was attributed to your account. `WEB` — cookie-based
web attribution via your deep-link. `APP` — attributed via mobile
app. `COUPON` — attributed via a coupon code with your affiliate
prefix.
utmSource:
type:
- string
- 'null'
description: >-
UTM source captured from the affiliate click cookie. Null if not
set.
utmMedium:
type:
- string
- 'null'
description: >-
UTM medium captured from the affiliate click cookie. Null if not
set.
utmCampaign:
type:
- string
- 'null'
description: >-
UTM campaign captured from the affiliate click cookie. Null if not
set.
AffiliateBookingUser:
type: object
description: Basic user information for the booking.
properties:
language:
type:
- string
- 'null'
description: >-
BCP 47 language code of the user at the time of booking (e.g., `en`,
`de`, `fr`).
country:
type:
- string
- 'null'
description: >-
ISO 3166-1 alpha-2 country code of the user's home country (e.g.,
`US`, `GB`, `IN`).
device:
type: string
enum:
- WEB
- APP
description: Platform the user was on when the booking was made.
AffiliateBookingVariant:
type: object
description: Variant details for the booking.
properties:
id:
type: string
description: Headout variant (tour) ID.
name:
type: string
description: Variant name.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Headout-Auth
````