Booking

The following APIs let a third-party system sell admission tickets for a merchant's products. A product is an admission (ticket) in e-guma that has been explicitly released for third-party sale.

This article gives an overview of the typical booking flow and lists the endpoints you will use. For details on each endpoint, follow the links in the sections below.

Prerequisites

Before you can call any endpoint:

• The merchant must have created an API key for the integration user.
• The admissions (products) you want to sell must have the Third party integrations sales channel enabled and the API key's user must be listed on them.
• The products must be compatible with third-party sales. Some configurations (e.g. mandatory customer notes, required ticket questions, per-ticket contact details, non-QR ticket media) cannot be completed end-to-end through the API and are filtered out of the List of Products API without warning. If a product you expect is not returned, ask the merchant to verify its setup.

Booking flow

The typical flow for selling a ticket looks like this:

1. Discover products. Call the List of Products API to get the set of products that are available for sale for this API key, together with their person categories and whether they are sold on a per-day or per-slot basis.
2. Fetch availabilities. For the product the customer picked, call the List of Availabilities API with a date range to get the bookable days or time slots, the price per category, quantity constraints and the cut-off time.
3. (Optional) Reserve the tickets. If some time will pass between the customer's choice and the payment, call the Reserve Tickets API to place a 60-minute hold on the selected availability. This avoids overselling during the checkout.
4. Book the tickets. Once the sale is confirmed on your side (payment captured, etc.), call the Book Tickets API to create the order and issue the tickets. Bookings require an Idempotency-Key header; see the Idempotency article.
5. (If needed) Cancel. Reservations that are no longer needed can be released before they expire with the Cancel Reservation API. Confirmed bookings can be cancelled with the Cancel Booking API as long as the start date is still in the future and no ticket has been checked in.

sequenceDiagram
  participant Client as Third-party system
  participant API as e-guma API

  Client->>API: GET /ticketing/products.json
  API-->>Client: Products + categories

  Client->>API: GET /ticketing/products/{id}/availabilities.json
  API-->>Client: Availabilities + prices

  opt Reservation
    Client->>API: POST /ticketing/reservation.json
    API-->>Client: reservation_id (valid 60 min)
  end

  Client->>API: POST /ticketing/booking.json (Idempotency-Key)
  API-->>Client: booking_id + tickets

  opt Cancellation
    Client->>API: POST /ticketing/cancel-booking.json
    API-->>Client: cancelled_tickets
  end

Endpoints at a glance

Mapping products to your system

We recommend persisting a mapping between each e-guma product_id (and its category_id values) and the corresponding product in your own system, rather than relying on product names. The plain name and description on a product (and on each person category) are convenience copies for the merchant's default language; the full name_translations and description_translations dictionaries return the same content keyed by ISO 639-1 language code so you can render the product directly in the customer's language without maintaining your own copy.

If you do keep your own localised names internally, the *_translations maps are still useful as the source of truth when a merchant adds a new language to a product.

Ticket downloads

The Book Tickets API returns absolute, token-protected download URLs for every issued ticket: a single PDF that bundles all tickets of the booking, plus a PDF — and, when the merchant has Apple Wallet enabled, an Apple Wallet pass (.pkpass) — per individual ticket. The links work without authentication and stay valid as long as the booking is not cancelled, so you can hand them straight to the customer (e.g. in your own confirmation email or order page). The tickets are rendered in the order's resolved language; supply the language field on the booking request when you need a specific one.

Idempotency, errors and retries

• Write endpoints that require it use an idempotency key, which lets you retry safely without creating duplicates. See the Idempotency article.
• All endpoints return standard HTTP status codes. Error responses have the shape { "error_code": "...", "message": "..." }. Do not parse message for logic; branch on error_code and the HTTP status code.
• Authentication failures return 401 unauthorized. Access to a product that is not enabled for this API key returns 403 forbidden or 404 not_found depending on the cause. Validation problems return 400 validation_error.