List Product Availabilities

GET {{baseUrl}}/products/:product_id/availability?from_date=2021-06-28

The availability API is used to make sure that the product or service is available on the desired date and time slot.

Depending on the product_availability parameter given in the product feed, the availability needs to be requested using this endpoint prior to making a booking.

This endpoint should be called in order to get up-to-date availability information for a product with managed capacity. The response will contain the availability for each time slot of the requested product that lies within the specified date range. Time slots will not be omitted in case of no availability. Neither will a NO_AVAILABILITY error be returned in that case. Instead, an explicit vacancy of zero should be expected.

Caching Recommendations

We only recommend caching if you would like to show availability for multiple products at once or for example hide fully booked products in a general overview page. Consider carefully whether caching is needed.

An example caching policy:

  • Before every order, we recommend checking the availability again to get the exact price and availability.
  • Once per hour, update the availability for the coming week.
  • Once per day, update the availability for the coming month.
  • Once per week, update the availability for the coming 90 days.

  • To further improve accuracy, you could tweak intervals based on the popularity or remaining capacity of the product. For example, only regularly fetch availabilty once the remaining capacity falls below 100.

Notes

  • Dates and times are always relative to the supplier timezone and all offsets are automatically adjusted based on daylight saving time (DST).
  • A maximum of 90 days is allowed. If you would like to batch availability for a longer period, please make multiple calls.

Request Params

KeyDatatypeRequiredDescription
distributor_idstring[FILTER] on distributor_id.
from_datestring(Required) [FILTER] From which date availability is requested.
If supplied with to_date , then availability request is for a date range.
If supplied without to_date, then for a single date availability is requested.
to_datestring[FILTER] Till which date availability is requested.
If this is empty, availability will be searched for the given from_date only.
include_disabledboolean[FILTER] Include disabled / closed (availability_active:false) entries.
availability_capacity_idstring[FILTER] on availability_capacity_id.
spots_open_minnumber[FILTER] The minimum remaining availability_spots_open.
sub_products_depthnumber[FILTER] The iteration depth of the included entries of the sub-products in the response. This will not apply to sub-products which have shared capacity linked to the main product.

Example Setup:

Product 101 (Main)
 Product 201 (Sub)
 Product 301 (Nested)
 Product 302 (Nested)
 Product 202 (Sub)
 Product 401 (Nested)
 Product 402 (Nested)
  • sub_products_depth:0 will return Product 101.
  • sub_products_depth:1 will return Product 101, 201 and 202.
  • sub_products_depth:2 will return Product 101, 201, 202, 301, 302, 401 and 402. | | availability_modified | string | | [FILTER] Only show entries modified after the given date. |

RESPONSES

status: OK

{"api_version":"3.4.0","data":{"items":[{"availability_active":true,"availability_created":"1974-01-04T21:35:37.830Z","availability_from_date_time":"1982-06-22T09:52:39.479Z","availability_id":"20191026090010006526","availability_modified":"1952-11-08T14:48:51.492Z","availability_capacity_id":"43525235","availability_capacity_shared_id":"435252453","availability_label":"Morning","availability_product_id":"3532","availability_duration":3600,"availability_to_date_time":"1997-03-14T14:31:04.595Z","availability_spots":{"availability_spots_open":75,"availability_spots_total":100,"availability_spots_reserved":15,"availability_spots_booked":10,"availability_spots_redeemed":10,"availability_spots_details":[{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}]},"availability_pricing":[{"availability_pricing_variation_amount":"-3.00","availability_pricing_variation_percentage":"20.00","availability_pricing_variation_description":"Peak hour","availability_pricing_variation_price_type":"SALES_PRICE","availability_pricing_variation_product_type_id":"PRODUCT_TYPE_ID_123","availability_pricing_variation_product_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}},{"availability_pricing_variation_amount":"-3.00","availability_pricing_variation_percentage":"20.00","availability_pricing_variation_description":"Peak hour","availability_pricing_variation_price_type":"SALES_PRICE","availability_pricing_variation_product_type_id":"PRODUCT_TYPE_ID_123","availability_pricing_variation_product_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}}],"availability_notes":[{"note_creator":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_date":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_value":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}},{"note_creator":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_date":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_value":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}}]},{"availability_active":true,"availability_created":"1950-04-09T10:54:43.071Z","availability_from_date_time":"1977-08-15T12:34:22.245Z","availability_id":"20191026090010006526","availability_modified":"1963-11-19T00:54:39.713Z","availability_capacity_id":"43525235","availability_capacity_shared_id":"435252453","availability_label":"Morning","availability_product_id":"3532","availability_duration":3600,"availability_to_date_time":"2001-05-25T22:19:06.774Z","availability_spots":{"availability_spots_open":75,"availability_spots_total":100,"availability_spots_reserved":15,"availability_spots_booked":10,"availability_spots_redeemed":10,"availability_spots_details":[{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}]},"availability_pricing":[{"availability_pricing_variation_amount":"-3.00","availability_pricing_variation_percentage":"20.00","availability_pricing_variation_description":"Peak hour","availability_pricing_variation_price_type":"SALES_PRICE","availability_pricing_variation_product_type_id":"PRODUCT_TYPE_ID_123","availability_pricing_variation_product_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}},{"availability_pricing_variation_amount":"-3.00","availability_pricing_variation_percentage":"20.00","availability_pricing_variation_description":"Peak hour","availability_pricing_variation_price_type":"SALES_PRICE","availability_pricing_variation_product_type_id":"PRODUCT_TYPE_ID_123","availability_pricing_variation_product_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}}],"availability_notes":[{"note_creator":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_date":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_value":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}},{"note_creator":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_date":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_type":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"},"note_value":{"value":"\u003cError: Too many levels of nesting to fake this schema\u003e"}}]}],"kind":"location","total_items":10}}