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 making a booking in the XS2Event.com.

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 adminstrative 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 find out what guest requirement are for a specific event.

See the chapter about guest data for more information and specifics.

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 the create reservation endpoint.

Once a reservation is created, you will have 10 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 in /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 explanining what went wrong.

Providing guest data

Now that you have a reservation and know what guest is required, you can provide the guestdata to the reservation.

We have a Add reservation guestdata endpoint which you can use to provide the guestdata:

{
  "items": [
    {
      "quantity": 2,
      "ticket_id": "ticket_123456",
      "guests": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "lead_guest": true
        }
      ]
    }
  ]
}

This endpoint will give a 422 response code if you're not providing information that is required right now (pre_checkout):

{
  "type": "/errors/invalid-guest-data",
  "title": "Invalid or missing guest data",
  "message": "Invalid or missing guest data",
  "detail": "Fields required before checkout are missing or have invalid values",
  "items": [
    {
      "ticket_id": "ticket_123456",
      "quantity": 2,
      "guests": [
        {
          "first_name": {
            "value": "John",
            "condition": "pre_checkout",
            "error": null
          },
          "last_name": {
            "value": "Doe",
            "condition": "pre_checkout",
            "error": null
          },
          "date_of_birth": {
            "value": null,
            "condition": "pre_checkout",
            "error": "required"
          },
          "country_of_residence": {
            "value": null,
            "condition": "pre_checkout",
            "error": "required"
          },
          "lead_guest": true
        }
      ]
    }
  ]
}

Finalizing your booking

At this point we assume that:

• your reservation is still valid
• you have provided us with the guestdata 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:

{
  "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 bookingorders from booking

When you create a booking, you will get the booking_id in the response. You can then use the Get bookingorders] to fetch all (usually one) bookingorders using the booking_id parameters.

In the result, you will then get the bookingorder_id for all the bookingorders that were created.

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 a errornous booking_email

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

Providing guest data later

As explained in the guest data page, there are situations where we allow you to provide the guest data later on.

For example the event is far away and supplier of the ticket accepts guest data later.

To find out which guest data you need to provide, you can use the Get bookingorder guestdata.

You can then either update all the guest data in one go using the Update bookingorder guestdata endpoint.

Or update per guest via the Update bookingorder guestdata for one guest endpoint.