> ## 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 available inventory for a variant
> We are soon moving to **v2 APIs** and **v1** will be deprecated. Switch to **v2** using the version selector above.
Get available time slots and pricing for a specific variant within an optional date range.
Returns inventory items with `startDateTime`/`endDateTime`, availability status, remaining capacity, and per-person or group pricing.
Use this to display bookable slots and prices to users before creating a booking.
## OpenAPI
````yaml GET /api/public/v1/inventory/list-by/variant/
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/inventory/list-by/variant/:
get:
tags:
- Inventory
summary: List available inventory for a variant
description: >-
We are soon moving to **v2 APIs** and **v1** will be
deprecated. Switch to **v2** using the version selector above.
Get available time slots and pricing for a specific variant within an
optional date range.
Returns inventory items with `startDateTime`/`endDateTime`, availability
status, remaining capacity, and per-person or group pricing.
Use this to display bookable slots and prices to users before creating a
booking.
operationId: v1ListInventoryByVariant
parameters:
- name: variantId
in: query
required: true
schema:
type: string
description: ID of the variant to list inventory for.
- name: startDateTime
in: query
schema:
type: string
format: date-time
description: >-
Start of the date range to fetch inventory for (format:
`yyyy-MM-dd'T'HH:mm:ss`). Defaults to the current timestamp if not
provided.
- name: endDateTime
in: query
schema:
type: string
format: date-time
description: >-
End of the date range to fetch inventory for (format:
`yyyy-MM-dd'T'HH:mm:ss`). Defaults to no end limit (returns all
future slots) if not provided.
- name: offset
in: query
schema:
type: integer
default: 0
description: Number of items to skip before starting to collect the result set.
- name: limit
in: query
schema:
type: integer
default: 10
description: Maximum number of items to return.
- name: currencyCode
in: query
schema:
type: string
description: Currency code for inventory pricing.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedInventory'
example:
items:
- id: '486135052'
startDateTime: '2026-03-25T09:00:00'
endDateTime: '2026-03-25T22:00:00'
availability: LIMITED
remaining: 27
pricing:
persons:
- type: ADULT
name: Adult
description: null
ageFrom: 13
ageTo: 61
price: 54.44
originalPrice: 54.44
netPrice: 54.44
headoutSellingPrice: 54.44
remaining: 27
availability: LIMITED
paxRange:
min: null
max: null
- type: CHILD
name: Child
description: null
ageFrom: 6
ageTo: 12
price: 49
originalPrice: 49
netPrice: 49
headoutSellingPrice: 49
remaining: 27
availability: LIMITED
paxRange:
min: null
max: null
- type: SENIOR
name: Senior
description: null
ageFrom: 62
ageTo: null
price: 52.26
originalPrice: 52.26
netPrice: 52.26
headoutSellingPrice: 52.26
remaining: 27
availability: LIMITED
paxRange:
min: null
max: null
groups: []
nextUrl: >-
https://www.headout.com/api/public/v1/inventory/list-by/variant?variantId=38164¤cyCode=USD&offset=1&limit=1
prevUrl: null
total: 12608
nextOffset: 1
security:
- apiKeyAuth: []
x-codeSamples:
- lang: curl
source: >
curl --location
'https://www.headout.com/api/public/v1/inventory/list-by/variant/?variantId=2671&offset=0&limit=150¤cyCode=AED'
\
--header 'Headout-Auth: '
components:
schemas:
PaginatedInventory:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Inventory'
description: The inventory slots in this page of results.
nextUrl:
type:
- string
- 'null'
description: >-
Full URL to fetch the next page of results. Null if on the last
page.
prevUrl:
type:
- string
- 'null'
description: >-
Full URL to fetch the previous page of results. Null if on the first
page.
total:
type: integer
description: Total number of available inventory slots across all pages.
nextOffset:
type:
- integer
- 'null'
description: >-
Offset value to use in the next request to retrieve the following
page.
Inventory:
type: object
properties:
id:
type: string
description: >-
Inventory slot identifier. Pass this as `inventoryId` when creating
a booking.
startDateTime:
type: string
format: date-time
description: >-
Start time for this slot in local time, no timezone offset (format
`yyyy-MM-dd'T'HH:mm:ss`).
Interpretation depends on the variant's `inventoryType`:
- `FIXED_START_*`: the exact time the experience begins (e.g., show
curtain time).
- `FLEXIBLE_START_*`: the venue or window opening time — not a fixed
entry time. The customer can arrive any time after this.
endDateTime:
type: string
format: date-time
description: >-
End time for this slot in local time, no timezone offset (format
`yyyy-MM-dd'T'HH:mm:ss`).
Interpretation depends on the variant's `inventoryType`:
- `FIXED_START_FIXED_DURATION`: the exact time the experience ends.
- `FIXED_START_FLEXIBLE_DURATION` / `FLEXIBLE_START_*`: the venue or
window closing time — the customer must depart by this time.
availability:
type: string
enum:
- LIMITED
- UNLIMITED
- CLOSED
description: >-
Availability status for this slot. See [Inventory
Availability](/guide/enums-and-error-codes#inventory-availability).
- `LIMITED`: limited spots — check `remaining` for the exact count.
- `UNLIMITED`: no cap on bookings for this slot.
- `CLOSED`: slot is unavailable and cannot be booked.
remaining:
type: integer
description: >-
Number of spots remaining. Relevant when `availability` is
`LIMITED`; may be approximate.
pricing:
type: object
description: >-
Current pricing for this inventory slot. Use these prices when
constructing a booking request.
properties:
persons:
type: array
description: >-
Per-person pricing tiers. Populated only when the variant's
`priceType` is `PER_PERSON`.
Empty for `PER_GROUP` variants.
items:
type: object
description: Per-person pricing tier.
properties:
type:
type: string
description: >-
Person category identifier (e.g., `ADULT`, `CHILD`,
`SENIOR`). Use this as `personType` in the booking
request.
name:
type: string
description: >-
Display label for this person type (e.g., "Adult",
"Child").
description:
type:
- string
- 'null'
description: >-
Additional details about this person type (e.g., age
restrictions or eligibility notes).
ageFrom:
type: integer
description: Minimum age (inclusive) qualifying for this person type.
ageTo:
type:
- integer
- 'null'
description: >-
Maximum age (inclusive) qualifying for this person type.
Null means no upper age limit.
price:
type: number
format: double
description: >-
Deprecated. Do not use this field in booking requests —
use `netPrice` in the same object instead.
originalPrice:
type: number
format: double
description: >-
Full price before discounts. Useful for showing
strikethrough pricing.
netPrice:
type: number
format: double
description: >-
Partner net amount per person after any discounts. Use
this value (not `price` or `headoutSellingPrice`) in the
booking request price.
headoutSellingPrice:
type: number
format: double
description: >-
The price at which Headout sells this experience on its
own channels. May differ from the partner price.
remaining:
type: integer
description: >-
Number of spots remaining for this person type
specifically.
availability:
type: string
enum:
- LIMITED
- UNLIMITED
- CLOSED
description: Availability for this person type specifically.
paxRange:
type: object
description: Allowed booking quantity range for this person type.
properties:
min:
type:
- integer
- 'null'
description: >-
Minimum number of this person type required per
booking.
max:
type:
- integer
- 'null'
description: >-
Maximum number of this person type allowed per
booking.
groups:
type: array
description: >-
Group pricing tiers. Populated only when the variant's
`priceType` is `PER_GROUP`.
Empty for `PER_PERSON` variants.
items:
type: object
description: >-
Group pricing tier (fixed price for a set group size,
regardless of individual person types).
properties:
size:
type: integer
description: >-
Upper bound (inclusive) of the group size this tier
applies to. The lower bound is the `size` of the next
smaller tier plus one (or 1 if this is the smallest tier).
Example: tiers with sizes [4, 7, 10] mean: 1-4 people =
tier[0].price, 5-7 people = tier[1].price, 8-10 people =
tier[2].price.
description:
type:
- string
- 'null'
description: Additional details about this group pricing tier.
price:
type: number
format: double
description: Current group price after any discounts.
originalPrice:
type: number
format: double
description: Full group price before discounts.
netPrice:
type: number
format: double
description: >-
The net amount remitted to Headout after partner
commission is deducted.
headoutSellingPrice:
type: number
format: double
description: >-
The price at which Headout sells this experience on its
own channels. May differ from the partner price.
remaining:
type: integer
description: Number of spots remaining for this group pricing tier.
availability:
type: string
enum:
- LIMITED
- UNLIMITED
- CLOSED
description: Availability status for this group pricing tier.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Headout-Auth
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.