Booking process
Introduction 📅
The booking process is crucial for ensuring a seamless user experience. It allows users to secure and confirm activity slots through our API. We recommend making a reservation to secure a spot before proceeding with booking and payment. Availability data may not be immediately updated due to caching in our system or the connected reservation and ticketing systems. We regularly update our slots every 4 hours, but demand for nature and Swiss mountain tours is high.
Here we visualize a typical booking process of a Tours & Activity E-Commerce Shop:
Reservation, Booking, Payment & Cancellation Process 🔄
After you have the activityID, availabilityID, and ticketCategorySelection, you can start the booking process. Key points to remember:
- Reservation Timing: Reservations are held for 15 minutes by default. If not confirmed within this window, they will expire.
- No Manual Tickets: All tickets are electronic. Manual ticketing is not supported. If a transaction fails, ensure to retry the reservation or refund your customer.
Let's start with the reservation process.
Step 1: Reservation 🕒
To initiate the booking process, begin with a reservation. This step temporarily reserves the desired slots, safeguarding against availability discrepancies and provides a live response.
POST /reservation
Request Body
{
"activityId": 0,
"availabilityId": "string",
"cartId": "string",
"doCreateCart": true,
"locale": "string",
"ticketCategorySelection": [
{
"numGuests": 0,
"ticketCategoryId": 0,
"guests": [
{
"personalizedData": [
{
"key": "string",
"value": "string"
}
]
}
],
"locale": "string",
"personalizedData": [
{
"key": "string",
"value": "string"
}
]
}
]
}
With the response, you can continue in the flow:
{
"reservationId": "string",
"cartId": "string",
"startsAt": "string",
"endsAt": "string",
"isAllDay": true,
"personalizationData": [
"string"
],
"createdAt": "string",
"expiresAt": "string",
"cancelledAt": "string",
"confirmedAt": "string",
"totalPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"isBooked": true,
"description": "string",
"axessTime": "string",
"ticketReservations": [
{
"ticketReservationId": 0,
"ticketCategoryLabel": "string",
"audience": "string",
"discountType": "string",
"occupancyType": "string",
"seatPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"ticketCategory": {
"ticketCategoryId": 0,
"note": "string",
"articlePrice": "string",
"articleLabel": "string",
"occupancyType": "string",
"label": {
"formatted": "string",
"audience": "string"
}
},
"offer": {
"offerId": 0,
"label": "string",
"contentApiId": 0
},
"guests": [
{
"guestId": "string",
"givenName": "string",
"familyName": "string",
"email": "string",
"occupancy": 0,
"personalizationData": [
"string"
]
}
]
}
]
}
Keep the cartID in storage in order to update the cart or checkout.
Step 2: Update Cart 🛒
If the pre-reservation is successful, the next step involves either creating a new cart or updating an existing one with the reservation details.
PATCH /carts/{cartId}/update
{
"reservationIds": [
"string"
],
"rebateCodes": [
"string"
]
}
Step 3: Initiate Booking Confirmation ✔️
After the reservations are secured in the cart, initiate the booking confirmation with:
PATCH /carts/{cartId}/checkout
{
"user": {
"email": "string",
"familyName": "string",
"givenName": "string",
"phone": "string"
}
}
Important: We do not accept bookings without a main user. Most suppliers want a contact in case of a short rebooking or unexpected cancellation due to weather or similar issues.
Response
{
"bookingId": "string",
"status": "string",
"paymentStatus": "string",
"createdAt": "string",
"paidAt": "string",
"totalGross": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"totalNet": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"vat": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"totalPayments": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"totalRefunds": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"outstanding": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"totalRebates": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"user": {
"userId": 0,
"givenName": "string",
"familyName": "string",
"email": "string",
"phone": "string"
},
"description": [
"string"
],
"items": [
{
"bookingItemId": "string",
"startsAt": "string",
"endsAt": "string",
"service": {
"activity": "string",
"offer": "string"
},
"reservations": [
{
"reservationId": "string",
"cart": {
"cartId": "string"
},
"startsAt": "string",
"endsAt": "string",
"isAllDay": true,
"personalizationData": [
"string"
],
"createdAt": "string",
"expiresAt": "string",
"cancelledAt": "string",
"confirmedAt": "string",
"totalPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"isBooked": true,
"description": "string",
"axessTime": "string",
"ticketReservations": [
{
"ticketReservationId": 0,
"ticketCategoryLabel": "string",
"audience": "string",
"discountType": "string",
"occupancyType": "string",
"seatPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"ticketCategory": {
"ticketCategoryId": 0,
"note": "string",
"articlePrice": "string",
"articleLabel": "string",
"occupancyType": "string",
"label": {
"formatted": "string",
"audience": "string"
}
},
"offer": {
"offerId": 0,
"label": "string",
"contentApiId": 0
},
"guests": [
{
"guestId": "string",
"givenName": "string",
"familyName": "string",
"email": "string",
"occupancy": 0,
"personalizationData": [
"string"
]
}
]
}
]
}
],
"isAllDay": true,
"guests": [
{
"guestId": "string",
"occupancy": 0,
"personalizationData": [
"string"
],
"tickets": [
{
"ticketId": "string",
"externalTicketCode": "string",
"externalTicketCodeType": "string",
"customerName": "string"
}
],
"pdf": {
"status": "string",
"uri": "string"
},
"ticketCategoryLabel": "string",
"seatPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"totalPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"articleLabel": "string",
"articlePrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
}
}
],
"totalPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"description": [
"string"
]
}
]
}
Booking Cancellation 🚫
Introduction
Cancellations are an inevitable part of managing bookings. To handle cancellations efficiently and understand the reasons behind them, it's essential to include a cancellation note with each request.
Cancel Booking Item
To cancel a specific booking item, use the endpoint below. This method allows detailed information about the cancellation's cause, which can be invaluable for service improvement and understanding customer needs.
PATCH /booking_items/{bookingItemId}/cancel
Request Parameters
- bookingItemId (string): The unique identifier for the booking item to be canceled.
Request Body
{
"cancellationNote": "Reason for cancellation"
}
This JSON payload should include a cancellationNote field to specify the reason for the cancellation.
Response
The API processes the cancellation and provides feedback on the operation's success. Additional information regarding refunds or other related actions might also be returned, depending on the setup.
{
"bookingItemId": "string",
"service": {
"activity": "string",
"offer": "string"
},
"startsAt": "string",
"endsAt": "string",
"description": [
"string"
],
"totalPrice": {
"amount": "string",
"currency": "string",
"formatted": "string"
},
"isCancellable": true
}
Need Help? 🆘
If you do not have your own PSP (Payment Service Provider) solution and require assistance with handling payments or cancellations, please don't hesitate to reach out. We are here to help streamline your payment and booking processes.
📧 Contact us at [email protected] for support and integration assistance.
Updated 6 months ago