Hold availability

A hold availability request is sent to hold/block availability, ensuring that a future booking is guaranteed within a pre-defined period. This gives the customer a reasonable amount of time to add something to cart and complete details for checkout.

During the contracting phase, suppliers will agree to a hold_duration period for hold availability requests. Once this period has passed, a successful booking for the same availability is no longer guaranteed.

Request and response

Request endpoint: POST {supplier_url}/hold

A hold availability request contains the following properties:

Request Body schema: application/json

experience_id required	string^(?!\-\|\.\|\_)[0-9a-z\-\.\_]{1,50}$ The experience ID.
expiration_time required	string <date-time> When the hold availability request can expire, based on the agreed upon `hold_duration` value. The value for this property must be in the local time for the experience with no time zone information, following the ISO 8601 standard.
hold_id required	string <uuid> The ID of the hold availability request.
option_id required	string^(?!\-\|\.\|\_)[0-9a-z\-\.\_]{1,50}$ The option ID.
pickup_id	string^(?!\-\|\.\|\_)[0-9a-z\-\.\_]{1,50}$ The pickup ID, if any.
required	Array of objects unique An array of the requested holder categories and their quantities.
slot_id required	string^(?!\-\|\.\|\_)[0-9a-z\-\.\_]{1,50}$ The availability slot ID.

The response to a successful hold availability request contains the following properties:

Hold availability request accepted

Response Schema: application/json

hold_id required	string The hold ID from the request.
transaction_id required	string The supplier's own ID for the hold request.

Capacity and quantity limits

Before a hold request is sent, PORTA validates the requested quantities against the following properties:

Option's min_booking_quantity and max_booking_quantity
Availability slot's capacity
Available holder category's min_quantity and max_quantity

If any of these properties are missing in PORTA, their validation is skipped. If any of the requested quantities is invalid, the requesting application receives an error and no hold availability request is sent to suppliers.

When setting up an experience, consider that some applications, like our own musement.com, do not directly communicate quantity limits to customers. To reduce errors that customers may encounter while placing an order, consider avoiding limits to the capacity/quantities contained within an experience.