Appearance

Booking flow ​

At this point, we assume you have implemented our API endpoints to fetch events and their corresponding tickets.

In this chapter we explain how to make a booking in the XS2Event.com system.

Please note that for each booking we apply a fixed fee per ticket. This fee will be mentioned on the invoice.

Models ​

For the booking flow, there are several models involved which will be referenced.

  1. Reservation, a temporary resource used to reserve (hold) tickets for you during the booking process.
  2. Booking, the top level resource of your entire booking.
  3. BookingOrder, an administrative part of your booking grouping the tickets for a specific event and supplier.
  4. GuestData, the information the supplier of the ticket requires.

A Booking can contain multiple BookingOrders—for example, if it includes tickets from different events or suppliers. However, most bookings will only have a single BookingOrder.

The number of GuestData entries depends on the supplier's requirements. It can be equal to the number of tickets, a subset (e.g., one per group), or even just a single entry.

Finding guest requirements ​

Before making a reservation you can already look up the requirements of an event. See Guest data.

Create a reservation ​

The best way to ensure the tickets your customers want are actually reserved for you is by making a reservation.

This can be done by using the create reservation endpoint.

Once a reservation is created, you will have 30 minutes to complete it.
After that it is voided and the tickets are no longer reserved for you.

DANGER

When creating a reservation, the net_rate and currency_code passed should be the same as the response from /v1/ticket/:ticket_id.

This is to ensure that your reservation matches your expectations and there is no doubt about the price.

Updating a reservation ​

You can always update a reservation, adding or removing tickets or changing quantities.

Do remember to check and update guest data if needed.

Reservation error situations ​

There are a few errors that can occur when making or updating a reservation:

  1. Out of stock
  2. Unknown ticket_id
  3. Price information send not matching our data
  4. Reservation has expired

The error response should contain all the details explaining what went wrong.

Providing guest data ​

Add the guest data to the reservation once you know what is required. The payload, the 422 response for missing pre_checkout fields and the later-update endpoints are described in Guest data.

Finalizing your booking ​

At this point we assume that:

  • your reservation is still valid
  • you have provided us with the guest data that was required (if applicable).

Now we can finalize your reservation and create a booking.

We do this using the Create booking endpoint.

Because we have made a reservation, we only need to provide some final information:

json
{
  "invoice_reference": "Reference to use on the invoice",
  "booking_email": "person.lastname@mycompany.com",
  "reservation_id": "our_reservation_id",
  "payment_method": "invoice"
}

Please make sure to use a payment method that is allowed in your contract.

Fetching booking orders from booking ​

The Create booking response contains both the booking_id and bookingorder_ids, the ids of all (usually one) booking orders that were created:

json
{
  "booking_id": "5867e9941e924a7bb169e244b26589ba_bkn",
  "reservation_id": "5e3ae0658c9e405a9a62367293b8f56b_rsr",
  "bookingorder_ids": [
    "e6bcb6ae4b6a4cf6a8f42b1c6f0a1d23_bko"
  ],
  "booking_code": "DQW32M"
}

So you no longer need an extra call to get the ids. Store them together with the booking_id.

If you need the full booking order objects (status, items, guest data requirements), use the Get booking orders endpoint, either filtered on the booking_id or on the bookingorder_ids you just received.

Booking error situations ​

At this point, there are still a few things that could go wrong:

  1. Your reservation expired
  2. You selected a payment method that is not valid or available
  3. You provided an erroneous booking_email

If your reservation expired, you can try to create a new one using the same ticket id(s).

Providing guest data later ​

If the supplier accepts guest data after checkout (pre_download fields), see Guest data.