4. Book Tickets

This endpoint creates a confirmed ticket order for a product. The generated tickets are immediately valid and belong to the merchant of the API key.

You can either call this endpoint directly, or after having placed a hold with the Reserve Tickets API.

Every call must include an Idempotency-Key HTTP header. See the Idempotency article for details on how to generate and handle idempotency keys.

POST https://api.e-guma.ch/v1/ticketing/booking.json?apikey={api-key}

Headers


Idempotency-Key `required`	Unique key for this booking attempt (e.g. a UUID). Re-sending the same request body with the same key will replay the original response instead of creating a new order. See the Idempotency article for full details.

Idempotency-Key required

Unique key for this booking attempt (e.g. a UUID). Re-sending the same request body with the same key will replay the original response instead of creating a new order.

See the Idempotency article for full details.

Parameters


api-key `required`	API key of a user that is approved for third-party integrations.

POST Data


reservation_id	Optional ID of a reservation previously created through the Reserve Tickets API.
product_id `required`	ID of the product. You can get the ID from the List of Products API.
starts_at `required`	Start date and time of the availability being booked, in ISO 8601 format. Use the starts_at returned by the List of Availabilities API. For day slots, pass only the date (or the date with a `00:00:00` time component). For time slots, pass the exact slot date and time.
items `required`	List of ticket items to book. At least one item is required. See item object below for details.
customer `required`	Customer for the booking. See customer object below for details.

Item object


category_id `required`	ID of the person category. Matches a category returned by the List of Products API.
quantity `required`	Number of tickets to book for this category. Must be greater than or equal to `0`. The value must respect the min_quantity, max_quantity and allow_zero_quantity constraints returned by the List of Availabilities API.

category_id required

ID of the person category. Matches a category returned by the List of Products API.

quantity required

Number of tickets to book for this category. Must be greater than or equal to 0.

The value must respect the min_quantity, max_quantity and allow_zero_quantity constraints returned by the List of Availabilities API.

Customer object


first_name `required`	First name of the customer.
last_name `required`	Last name of the customer.
email `required`	Email address of the customer.

Return


booking_id	ID of the booking (order). Store it for further actions (e.g. cancelling the booking .
booking_reference	Human readable booking reference (order number).
tickets	List of tickets generated for this booking. See ticket object below for details.

Ticket object


ticket_number	Ticket number. Use this value for the QR code on the ticket.
category_id	ID of the person category this ticket belongs to. Matches one of the category_id values sent in items.

Example

POST https://api.e-guma.ch/v1/ticketing/booking.json?apikey=510e32c594d84816a4af9df1
Idempotency-Key: 7f2d9e4b-1c33-4fab-8a42-abcdef123456

{
  "product_id": "64ad1bb1973b861c040c99bd",
  "starts_at": "2026-03-19T10:00:00",
  "items": [
    {
      "category_id": "64ad1bb1973b861c040c99c1",
      "quantity": 2
    }
  ],
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  }
}

{
  "booking_id": "50b6d149-49c4-4d2d-a96d-59d251de1edb",
  "booking_reference": "T10015",
  "tickets": [
    {
      "ticket_number": "4666825950402448933",
      "category_id": "64ad1bb1973b861c040c99c1"
    },
    {
      "ticket_number": "5520724186522287244",
      "category_id": "64ad1bb1973b861c040c99c1"
    }
  ]
}