Availability

Getting availability for a product

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.

Ventrata has two main availability calls:

POST /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.

POST /availability 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.

We will document both endpoints below.

Availability Calendar

POST https://api.ventrata.com/octo/availability/calendar

The availability calendar endpoint for quick retrieval of availability over a date range

Request Body

Name	Type	Description
productId	string	The product id
optionId	string	The option id
localDateStart	string	Start date to query for (YYYY-MM-DD)
localDateEnd	string	End date to query for (YYYY-MM-DD)
units[].id	string	The unit id
units[].quantity	integer	The quantity of the unit

200

[
  {
    "localDate": "2020-07-01",
    "status": "AVAILABLE",
    "available": true,
    "capacity": 24,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  },
  {
    "localDate": "2020-07-02",
    "status": "CLOSED",
    "available": false,
    "capacity": null,
    "openingHours": []
  }
]

The availability calendar can optionally take an array of units if you already know what they are and will automatically show availabilities as sold out if they have insufficient space.

POST /availability/calendar

{
  "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
  "optionId": "DEFAULT",
  "localDateStart": "2020-07-01",
  "localDateEnd": "2020-07-03",
  "units": [
    { "id": "unit_123abcadult", "quantity": 2 },
    { "id": "unit_321abcchild", "quantity": 1 }
  ]
}

The response will be an array of objects, one for each day between the range given in localDateStart and localDateEnd. Each object is defined as:

Field	Description
localDate	The date (in format YYYY-MM-DD)
status	The status of that date. Possible values are: AVAILABLE There are availabilities available on this date for sale. SOLD_OUT This date was available but is now fully sold out. LIMITED This date is available but has less than 50% capacity left. CLOSED This date is closed and not available for sale.
available	A boolean value (true or false) indicating whether you're able to sell tickets. This is basically just an alias for: status == 'AVAILABLE' || status == 'LIMITED'
capacity	The total capacity on this day. We cannot give exact vacancies on the calendar endpoint as this endpoint is cached for speed and is only meant to give an indication.
openingHours	A list of opening hours that the product is open on this day.
openingHours[].from	When this product opens (HH:MM)
openingHours[].to	When this product closes (HH:MM)

Availability Check

POST https://api.ventrata.com/octo/availability

Get final availability for a given product. If in doubt between the calendar endpoint and this one, you should use this endpoint.

Request Body

Name	Type	Description
productId	string	The product id
optionId	string	The option id
localDateStart	string	Start date to query for (YYYY-MM-DD)
localDateEnd	string	End date to query for (YYYY-MM-DD)
units[].id	string	The unit id
units[].quantity	integer	The quantity of the unit

200

[
  {
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T12:00:00-05:00",
    "localDateTimeStart": "2020-07-01T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:00:00-05:00",
    "utcCutoffAt": "2020-07-01T17:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T14:30:00-05:00",
    "localDateTimeStart": "2020-07-01T14:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T02:30:00-05:00",
    "utcCutoffAt": "2020-07-01T19:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T15:00:00-05:00",
    "localDateTimeStart": "2020-07-01T15:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T03:00:00-05:00",
    "utcCutoffAt": "2020-07-01T20:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  }
]

The availability calendar can optionally take an array of units if you already know what they are and will automatically show availabilities as sold out if they have insufficient space.

POST /availability

{
  "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
  "optionId": "DEFAULT",
  "localDateStart": "2020-07-01",
  "localDateEnd": "2020-07-03",
  "units": [
    { "id": "unit_123abcadult", "quantity": 2 },
    { "id": "unit_321abcchild", "quantity": 1 }
  ]
}

The response will be an array of availability objects which are defined below:

Field	Description
id	The availability id, you'll need this when booking
localDateTimeStart	The start time for this availability. This will be in the local time zone to the product.
localDateTimeEnd	The end time for this availability. This will be in the local time zone to the product.
allDay	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.
status	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 This availability is not LIMITED This availability is available but has less than 50% capacity left.

Depending on the value of product.availabilityType the response will keep the same structure but will generally look slightly different. We've provided examples of that below:

OPENING_HOURS

Products with this availabilityType are typically Museums, Attractions or Hop on Hop off tours where the guest just picks a date they wish to travel and can show up at any point whilst the product is open.

This is a typical response from a product with OPENING_HOURS availability type:

[
  {
    "id": "2020-07-01",
    "localDateTimeStart": "2020-07-01T00:00:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:59:59-05:00",
    "utcCutoffAt": "2020-07-01T05:00:00Z",
    "allDay": true,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": null,
    "capacity": null,
    "maxUnits": null,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  },
  {
    "id": "2020-07-02",
    "localDateTimeStart": "2020-07-02T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T23:59:59-05:00",
    "utcCutoffAt": "2020-07-02T05:00:00Z",
    "allDay": true,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": null,
    "capacity": null,
    "maxUnits": null,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  },
  {
    "id": "2020-07-03",
    "localDateTimeStart": "2020-07-03T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-03T23:59:59-05:00",
    "utcCutoffAt": "2020-07-03T05:00:00Z",
    "allDay": true,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": null,
    "capacity": null,
    "maxUnits": null,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  }
]

Notice how vacancies, capacity and max units are all null indicating unlimited, and the allDay flag is set true. You should just render this as a calendar with no further times to chose from once the guest has chosen the date.

START_TIME

Products with this availability type are typically walking tours, day trips and other activities where the guest has to book onto a specific departure time. There may be just one or multiple throughout the day.

This is a typical response from a product with START_TIME availability type:

[
  {
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T12:00:00-05:00",
    "localDateTimeStart": "2020-07-01T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:00:00-05:00",
    "utcCutoffAt": "2020-07-01T17:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T14:30:00-05:00",
    "localDateTimeStart": "2020-07-01T14:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T02:30:00-05:00",
    "utcCutoffAt": "2020-07-01T19:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "id": "2020-07-01T15:00:00-05:00",
    "localDateTimeStart": "2020-07-01T15:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T03:00:00-05:00",
    "utcCutoffAt": "2020-07-01T20:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  }
]

These are all availabilities for the same day. Once the guest has chosen the date (in this example 2020-07-01 then they must then pick a departure time. Again in this example the departure times would be:

• 11:00 AM

• 12:00 PM

• 2:30 PM

• 3:00 PM

Unlike the calendar endpoint, the availability check endpoint will not return an availability object if the product is closed. If there are no availabilities for a given date you should just mark it as closed in your interface.

Batch Availability Calendar

POST https://api.ventrata.com/octo/availability/calendar/batch

Get the availability calendar for all products and options. Use this endpoint only if you are refreshing a cache and need to fetch the availability calendar for all products.

Request Body

Name	Type	Description
localDateStart	string	Start date to query for (YYYY-MM-DD)
localDateEnd	string	End date to query for (YYYY-MM-DD)
productIds[]	string[]	Optional. List of productIds to filter by.
units[].type	string	Optional. Because the unit IDs can be different across products, we use type instead, values are: ADULT YOUTH CHILD INFANT FAMILY SENIOR STUDENT MILITARY OTHER
units[].quantity	integer	Optional. The quantity of units to look for.

The response is a long list of availability calendar objects (documented above as part of the Availability Calendar), except will include productId and optionId indicating what product/option that it belongs to.

200

[
  {
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "localDate": "2020-07-01",
    "status": "AVAILABLE",
    "available": true,
    "capacity": 24,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  },
  {
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "localDate": "2020-07-02",
    "status": "CLOSED",
    "available": false,
    "capacity": null,
    "openingHours": []
  },
  {
    "productId": "020cf5bf-0d81-4cd4-a55f-d85f23064c40",
    "optionId": "cdcf4749-35be-4907-b8bf-0240df02ff8b",
    "localDate": "2020-07-01",
    "status": "AVAILABLE",
    "available": true,
    "capacity": 24,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ],
  },
  {
    "productId": "020cf5bf-0d81-4cd4-a55f-d85f23064c40",
    "optionId": "cdcf4749-35be-4907-b8bf-0240df02ff8b",
    "localDate": "2020-07-02",
    "status": "AVAILABLE",
    "available": true,
    "capacity": 24,
    "openingHours": [
      { "from": "09:00", "to": "12:00" },
      { "from": "15:00", "to": "18:00" }
    ]
  }
]

Batch Availability

POST https://api.ventrata.com/octo/availability/batch

Get final availability for all products and options. Use this endpoint only if you are refreshing a cache and need to fetch availability for every product.

Request Body

Name	Type	Description
localDateStart	string	Start date to query for (YYYY-MM-DD)
localDateEnd	string	End date to query for (YYYY-MM-DD)
productIds[]	string[]	Optional. List of productIds to filter by.
units[].type	string	Optional. Because the unit IDs can be different across products, we use type instead, values are: ADULT YOUTH CHILD INFANT FAMILY SENIOR STUDENT MILITARY OTHER
units[].quantity	integer	Optional. The quantity of units to look for.

The response is a long list of availability objects (documented above as part of the Availability Check), except will include productId and optionId indicating what product/option that it belongs to.

200

[
  {
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
    "optionId": "DEFAULT",
    "id": "2020-07-01T12:00:00-05:00",
    "localDateTimeStart": "2020-07-01T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:00:00-05:00",
    "utcCutoffAt": "2020-07-01T17:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "productId": "020cf5bf-0d81-4cd4-a55f-d85f23064c40",
    "optionId": "cdcf4749-35be-4907-b8bf-0240df02ff8b",
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  },
  {
    "productId": "020cf5bf-0d81-4cd4-a55f-d85f23064c40",
    "optionId": "cdcf4749-35be-4907-b8bf-0240df02ff8b",
    "id": "2020-07-01T12:00:00-05:00",
    "localDateTimeStart": "2020-07-01T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:00:00-05:00",
    "utcCutoffAt": "2020-07-01T17:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "available": true,
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": []
  }
]