Availabilities

Availability objects are used to convey an operator's ability to provide a service at a given time.

Reference can be found here

AvailabilityItem

An AvailabilityItem represents a point or period of time (depending on the parent Product's availabilityType) when the parent Product Option is available for booking.

When placing a booking, the AvailabilityItem ID is used as a reference to the desired reservation time. For this reason, it is important for Operator Booking Systems to have methods in place to resolve these IDs for future reference.

Field Name	Type	Required	Description
`id`	string	Yes	Unique identifier for this Availability within the Product Option
`optionId`	string	Yes	ID of the Option this availability is under, unique within the Product.
`localDateTimeStart`	string(RFC3339)	Yes	The start time (inclusive) of the availability
`localDateTimeEnd`	string(RFC3339)	Yes	The end time (inclusive) of the availability
`status`	string(AvailabilityStatus)	Yes	Indicates whether the availability is bookable, and provides additional context
`vacancies`	integer	No	Number of units available for this option at this time. Additional information on Vacancies can be found below

Examples

// AvailabilityItems under a Product // with an availabilityType of 'OPENING_HOURS' // and located in Denver, Colorado. // The Product Option 'Option 1' is available for 8 // contiguous hours a day, from 9 to 5 local time, // and does not track capacity. [ { "id": "2021-02-01", "optionId": "Option1", "localDateTimeStart": "2021-02-01T09:00:00-07:00", "localDateTimeEnd": "2021-02-01T17:00:00-07:00", "status": "FREESALE" }, { "id": "2021-02-02", "optionId": "Option1", "localDateTimeStart": "2021-02-02T09:00:00-07:00", "localDateTimeEnd": "2021-02-02T17:00:00-07:00", "status": "FREESALE" } ]

// AvailabilityItems under a Product // with an availabilityType of 'START_TIME' // and located in New York City, New York. // The Product Option 'Option A' is available for 4 // hours a day, with a capacity of 10 for each // hour-long block of time. [ { "id": "2021-03-04-morning", "optionId": "Option A", "localDateTimeStart": "2021-03-04T08:00:00-05:00", "localDateTimeEnd": "2021-03-04T09:00:00-05:00", "status": "AVAILABLE", "vacancies": 8 }, { "id": "2021-03-04-brunch", "optionId": "Option A", "localDateTimeStart": "2021-03-04T10:30:00-05:00", "localDateTimeEnd": "2021-03-04T11:30:00-05:00", "status": "AVAILABLE", "vacancies": 10 }, { "id": "2021-03-04-lunch", "optionId": "Option A", "localDateTimeStart": "2021-03-04T13:00:00-05:00", "localDateTimeEnd": "2021-03-04T14:00:00-05:00", "status": "LIMITED", // LIMITED is arbitrary; this time slot may be sold out soon! "vacancies": 4 }, { "id": "2021-03-04-dinner", "optionId": "Option A", "localDateTimeStart": "2021-03-04T17:30:00-05:00", "localDateTimeEnd": "2021-03-04T18:30:00-05:00", "status": "SOLD_OUT", // This time slot has SOLD_OUT, but vacancies may free up later! "vacancies": 0 }, { "id": "2021-03-04-latenight", "optionId": "Option A", "localDateTimeStart": "2021-03-04T23:30:00-05:00", "localDateTimeEnd": "2021-03-05T00:30:00-05:00", "status": "CLOSED", // Sales at this time slot are CLOSED, but may become available later! "vacancies": 0 } ]

Note on DateTimes

localDateTimeStart and localDateTimeEnd must be provided as fully-qualified RFC3339 timestamps, including a UTC offset (or a suffix of Z for an offset of -00:00).

The offset provided MUST match the local timezone of the product option.

AvailabilityStatus

Name	Description
`FREESALE`	Always available
`AVAILABLE`	Currently available for sale, but has a fixed capacity
`LIMITED`	Currently available for sale, but has a fixed capacity and may be sold out soon
`SOLD_OUT`	Currently sold out, but additional availability may free up
`CLOSED`	Currently not available for sale, but not sold out (e.g. temporarily on stop-sell) and may be available for sale soon

Note on Vacancies

There are some additional rules and validations on how vacancies should be counted in availabilities.

If the availability has a status of FREESALE, vacancies should be omitted from the response - the FREESALE status implies an unlimited number of vacancies.
Vacancies should be considered the total capacity of the product. The number of vacancies returned will be considered available for all unit types returned.
It is recommended that vacancies be drawn from a general pool of vacancies shared among all Unit types within a Product Option.
Vacancies are only available at the Option level, if you need to set availability/vacancies at a traveler type level then an option should be created for each traveler type and the vacancy set there.

Last updated on

Was this page helpful?