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 find out what the guest requirements 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 using 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 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

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

We have an Add reservation guest data endpoint which you can use to provide the guest data:

{
  "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 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:

{
  "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

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

In the result, you will then get the bookingorder_id for all the booking orders 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 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

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 the supplier of the ticket accepts guest data later.

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

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

Or update per guest via the Update booking order guest data for one guest endpoint.