4. Book Tickets

This endpoint creates a 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. Each category_id must appear at most once — combine multiple tickets for the same person category into a single item with the summed quantity. See item object below for details.
customer `required`	Customer for the booking. See customer object below for details.
language	Optional ISO 639-1 language code (e.g. `de`, `en`, `fr`, `it`) used to render the order's tickets (PDF and Apple Wallet pass). Validation is strict: the value must be one of the languages the product has content in. Pick a value from the keys of name_translations in the List of Products API — anything else returns `400 validation_error` with the list of supported languages in message. When omitted, e-guma falls back to the merchant's default language if the product supports it, otherwise to the product's first available language. The resolved value is echoed back in the response.

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 `0`.

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).
language	ISO 639-1 language code the order was actually created in. Echoes the request's language when one was supplied; otherwise reveals the resolved fallback. The PDF and Apple Wallet downloads below are rendered in this language.
tickets_pdf_url	Absolute, token-protected URL to download a single PDF that contains all tickets of this booking. The link works without authentication, is valid as long as the booking is not cancelled, and renders the tickets in language.
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.
pdf_url	Absolute, token-protected URL to download the PDF for this individual ticket (same shape as tickets_pdf_url, but scoped to a single ticket). Works without authentication and stays valid as long as the booking is not cancelled.
pk_pass_url	Absolute, token-protected URL to download the Apple Wallet pass (`.pkpass`) for this ticket, or `null` when the merchant has Apple Wallet disabled.

Example

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

{
  "reservation_id": "69784d61a43bb308fdbf0a14",
  "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]"
  },
  "language": "en"
}

{
  "booking_id": "69d86bc39927d941d4dab89a",
  "booking_reference": "1000053",
  "language": "en",
  "tickets_pdf_url": "https://shop.e-guma.ch/demo/en/tickets/download?token=eyJvIjoi...orderToken",
  "tickets": [
    {
      "ticket_number": "4666825950402448933",
      "category_id": "64ad1bb1973b861c040c99c1",
      "pdf_url": "https://shop.e-guma.ch/demo/en/tickets/download?token=eyJvIjoi...ticket1Pdf",
      "pk_pass_url": "https://shop.e-guma.ch/demo/en/tickets/download?token=eyJvIjoi...ticket1Pass"
    },
    {
      "ticket_number": "5520724186522287244",
      "category_id": "64ad1bb1973b861c040c99c1",
      "pdf_url": "https://shop.e-guma.ch/demo/en/tickets/download?token=eyJvIjoi...ticket2Pdf",
      "pk_pass_url": "https://shop.e-guma.ch/demo/en/tickets/download?token=eyJvIjoi...ticket2Pass"
    }
  ]
}