Availability

The first step when making a sale is to check for availability. Note if allowFreesale is set to true on the product then this step is optional but it is advised you check it anyway if you can to check for closures.

OCTO has two main availability calls:

Availability Calendar endpoint is designed to be highly optimized and returns a single object per day. It's designed to be queried for large date ranges and the result is used to populate an availability calendar.

Availability Check endpoint may be slightly slower as it will return an object for each individual departure time (or day).

Availability Calendar

Availability Calendar

This endpoint is highly optimised and will return a single object per day. It's designed to be queried for large date ranges and the result is used to populate an availability calendar.

When the end user selects an open date you can call on /availability endpoint to get the availabilityId to create the booking.

POSThttps://api.example.com/octo/availability/calendar

Body

application/json

productId*string

The product id.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

optionId*string

The option id.

Example: "DEFAULT"

localDateStart*string

Start date to query for (YYYY-MM-DD).

Example: "2022-05-23"

localDateEnd*string

End date to query for (YYYY-MM-DD).

Example: "2022-05-29"

unitsarray of object

A list of units.

Response

200400

OK

Body

application/json

localDate*string (date)

A single date to query. Must be ISO 8601 compliant date.

Example: "2022-05-12"

available*boolean

Whether there is availability for this date / slot.

status*AvailabilityStatus

The status of that date. Possible values are: AVAILABLE This availability is available for sale FREESALE This availability has no capacity and is available. SOLD_OUT There are no more spots available for this date / slot. LIMITED This availability is available but has less than 50% capacity left. CLOSED Availability is closed for this day / slot.

Example: "AVAILABLE"

AVAILABLEFREESALESOLD_OUTLIMITEDCLOSED

vacancies*integernull

This SHOULD NOT be returned when status is FREESALE. This SHOULD be a shared pool for all Unit types in the Option. If availability is tracked per-Unit then this value MUST be equal to the available quantity for the Unit that has the most remaining.

Example: 10

capacity*integernull

The total capacity on this day.

Example: 10

openingHours*array of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/availability/calendar', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
      "optionId": "DEFAULT",
      "localDateStart": "2022-06-14",
      "localDateEnd": "2022-06-16"
    }),
});
const data = await response.json();

Response

200400

[
  {
    "localDate": "2022-05-12",
    "available": false,
    "status": "AVAILABLE",
    "vacancies": 10,
    "capacity": 10,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  }
]

Availability Check

A reseller has to perform Availability Check to retrieve an availabilityId in order to make a Booking Reservation, so this endpoint is critical for the booking flow.

Availability Check

This endpoint is slightly slower as it will return an object for each individual departure time (or day). You have to perform this step to retrieve an availabilityId in order to confirm a sale, so if you just want to use this endpoint and skip the calendar endpoint then that's perfectly ok.

You must pass in one of the following combinations of parameters for this endpoint:

• localDate
• localeDateStart and localDateEnd
• availabilityIds

POSThttps://api.example.com/octo/availability

Body

application/json

productId*string

The product id.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

optionId*string

The option id.

Example: "DEFAULT"

localDateStartstring (date)

Start date to query for (YYYY-MM-DD). Required if localDateEnd is set.

Example: "2022-05-23"

localDateEndstring (date)

End date to query for (YYYY-MM-DD). Required if localDateStart is set.

Example: "2022-05-29"

availabilityIdsarray of string

Filter the results by the given ids.

unitsarray of object

A list of units.

Response

200400

OK

Body

application/json

id*string

The availability id, you''ll need this when booking. MUST be a unique identifier within the scope of an option.

Example: "2022-05-23T00:00:00+01:00"

localDateTimeStart*string (date-time)

The start time for this availability. This will be in the local time zone of the product. Must be an ISO 8601 compliant date and time.

Example: "2022-05-23T00:00:00+01:00"

localDateTimeEnd*string (date-time)

The end time for this availability. This will be in the local time zone of the product. Must be an ISO 8601 compliant date and time.

Example: "2022-05-24T00:00:00+01:00"

allDay*boolean

A boolean field indicating whether this is an all day availability and not a fixed departure time. If this value is true then there will be no other availability object on the same day.

available*boolean

Whether there is availability for this date / slot.

status*AvailabilityStatus

The status of that date. Possible values are: AVAILABLE This availability is available for sale FREESALE This availability has no capacity and is available. SOLD_OUT There are no more spots available for this date / slot. LIMITED This availability is available but has less than 50% capacity left. CLOSED Availability is closed for this day / slot.

Example: "AVAILABLE"

AVAILABLEFREESALESOLD_OUTLIMITEDCLOSED

vacancies*integernull

This SHOULD NOT be returned when status is FREESALE. This SHOULD be a shared pool for all Unit types in the Option. If availability is tracked per-Unit then this value MUST be equal to the available quantity for the Unit that has the most remaining.

Example: 10

capacity*integernull

The total capacity on this day.

Example: 10

maxUnits*integernull

Maximum number of units that can be sold within one booking on this day / slot.

Example: 10

utcCutoffAt*string

The time by which the booking must be confirmed at

Example: "2022-05-22T23:00:00Z"

openingHours*array of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/availability', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
      "optionId": "DEFAULT",
      "localDateStart": "2022-05-23",
      "localDateEnd": "2022-05-29"
    }),
});
const data = await response.json();

Response

200400

[
  {
    "id": "2022-05-23T00:00:00+01:00",
    "localDateTimeStart": "2022-05-23T00:00:00+01:00",
    "localDateTimeEnd": "2022-05-24T00:00:00+01:00",
    "allDay": false,
    "available": false,
    "status": "AVAILABLE",
    "vacancies": 10,
    "capacity": 10,
    "maxUnits": 10,
    "utcCutoffAt": "2022-05-22T23:00:00Z",
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  }
]