Tickets

Admission tickets - day tickets, time-slot tickets, combo tickets. How to list, check availability, reserve, and add to an order.

A Ticket is one of go~mus's product types (e.g. Tickets, Tours, Events) and represents admission tickets in the broader sense - everything that lets visitors into the building. If you are integrating an online shop, a website with a booking flow or a reseller system, tickets are usually the first touchpoint.

This page explains the mental model and the most common workflows. The full endpoint and schema reference lives in the Swagger docs.

Ticket types

go~mus distinguishes three types that differ in availability semantics and required parameters:

ticket_typeWhenCheck availability via
normalAdmission on a date, no time window (day ticket)capacity - one number per day
time_slotAdmission in a slot (e.g. 14:00-14:30)capacities - array of slots per day
annualAnnual passes - separate endpoint and lifecycle, see Annual Ticketsn/a

Orthogonal to that there are flex tickets: tickets with free_timing: true are sold without a fixed date and can be redeemed any time within their validity. Functionally almost always a flavour of normal. Filter: ?by_free_timing=true.

bookable: true filters for what is publicly bookable for your auth context (public token, reseller token and cash-point token may see different sets, depending on configuration).

Anatomy of a ticket object

The index and detail responses regularly contain these fields per ticket:

  • id - stable primary key. Use it in order items, cart state and as a foreign key on your side
  • title, description - translatable via ?locale=de (see Concepts: Locale)
  • ticket_type - see above
  • price_cents, vat_pct, tax_included - base price. Pricing rules (member discount, time-based pricing) may modify the price at the order-item level
  • quota_ids - which quotas the ticket draws from (see Concepts: Quotas)
  • museum_ids, exhibition_ids - assignment to houses and special exhibitions
  • entry_duration - for time_slot: slot length in minutes. For normal: always null
  • free_timing - boolean. true = flex ticket (no fixed date at sale)
  • min_persons, max_persons - per-booking limits

Full field list including personalization, attendee requirements and validation flags: Swagger.

Endpoints at a glance

EndpointWhatWhen to use
GET /api/v4/ticketsList with base dataOverview, filtering, search
GET /api/v4/tickets/:idSingle ticket detailFull description, configuration
GET /api/v4/tickets/:id/capacityRemaining places for a date (slot map)"X tickets left" per slot
GET /api/v4/tickets/calendar?ticket_ids[]=...Bookability per day in a rangeDatepicker, grey out sold-out days
GET /api/v4/tickets/capacities?ticket_ids[]=...Capacities for several tickets, grouped by quotaSlot list across multiple tickets at once
POST /api/v4/tickets/reservationsBlock places temporarilyBefore order finalize
PUT /api/v4/tickets/reservations/:tokenChange quantity, extend lifetimeWhile the user is in checkout
DELETE /api/v4/tickets/reservations/:tokenRelease a reservationWhen the user abandons

Common tasks

List tickets

curl "https://demo.gomus.de/api/v4/tickets?by_bookable=true&locale=de"

Frequently used filters:

  • by_museum_ids[]=20&by_museum_ids[]=21 - tickets for specific houses only
  • by_exhibition_ids[]=2057 - tickets for one special exhibition
  • by_ticket_type=time_slot - time-slot tickets only (or normal, annual)
  • by_free_timing=true - flex tickets only
  • valid_at=2026-09-01 - the ticket set active on this reference date (default: today)

Fetch a ticket in detail

curl "https://demo.gomus.de/api/v4/tickets/247?locale=de"

The detail response contains the full description and additional configuration fields beyond what the index returns.

Check availability - single ticket

curl "https://demo.gomus.de/api/v4/tickets/247/capacity?date=2026-05-15"

Response shape:

{
  "data": {
    "2026-05-15T11:00:00+02:00": 15,
    "2026-05-15T11:30:00+02:00": 21
  }
}

Map of slot start time to remaining places. For time_slot tickets one entry per slot; for normal typically a single entry (day opening time). Capacity considers all quotas the ticket belongs to - for combo tickets the result is the minimum.

Check availability across several tickets

curl "https://demo.gomus.de/api/v4/tickets/capacities?ticket_ids[]=247&ticket_ids[]=248&date=2026-05-15"

Returns capacities grouped by quota id, with total_capacities (configured maximum) and capacities (currently available). Useful in checkout when several tickets share quotas and you want to display consistent remaining places.

Find available days (datepicker)

curl "https://demo.gomus.de/api/v4/tickets/calendar?ticket_ids[]=247&start_at=2026-05-01&end_at=2026-05-31"

Returns a boolean per day - useful to grey out sold-out days in a datepicker without one capacity call per day. Maximum 31 days per call. Pass depth=all instead of the default any to also get per-day quota and capacity information.

Create a reservation

curl -X POST "https://demo.gomus.de/api/v4/tickets/reservations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation": {
      "ticket_id": 247,
      "quantity": 2,
      "start_at": "2026-05-15T14:00:00+02:00"
    }
  }'

The response contains a token - use it for PUT/DELETE and on the final order item so the places are actually attached to your order.

Refresh a reservation or change quantity

curl -X PUT "https://demo.gomus.de/api/v4/tickets/reservations/RESERVATION_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reservation": { "quantity": 3 } }'

PUT extends the lifetime at the same time. If you want to keep a user in checkout while they take longer, you can send the same quantity again - it pushes the expiry forward.

Release a reservation

curl -X DELETE "https://demo.gomus.de/api/v4/tickets/reservations/RESERVATION_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN"

Important especially on checkout abandonment - otherwise the places are blocked until the reservation expires and other users will see them as "sold out".

Relationships

Ticket
 ├── Quota (1..n) ......... defines the availability semantics
 ├── Museum (1..n) ........ which houses the ticket belongs to
 ├── Exhibition (0..n) .... which special exhibitions
 ├── Reservation (0..n) ... temporary holds
 └── OrderItem ............ when booked, the ticket lives as an item on an order

A ticket can reference multiple quotas. This is common for combo tickets - the "Collection plus special exhibition" ticket draws places from two quota pools at once. Availability is then the minimum.

Pitfalls

  • valid_at is the reference date, not the booking date. Default is today. If you list tickets that should be active in 6 months (advance sale of a special exhibition), set valid_at accordingly, otherwise you only see what is active today.
  • bookable is context-dependent. With a public token you see bookable: true for tickets walk-in customers can buy. With a reseller token the set may differ - some tickets are publicly bookable: false but bookable for resellers. This is intentional and depends on configuration.
  • capacity (singular) and capacities (plural) are not interchangeable. Singular returns a number for a day (day ticket), plural returns an array of slots (time-slot ticket). Wrong endpoint = either an empty array or a meaningless number.
  • Capacities are live data - do not cache them. A 30-second-old capacity may already be stale by the time the user clicks book and you will hit a conflict at order finalize.
  • The reservation token is the ID. For PUT and DELETE, use the token from the create response, not the numeric ticket ID.
  • Reservations have a limited lifetime. Default is instance-specific (order of magnitude minutes). Plan to refresh if your checkout can take longer (e.g. login + address + payment). Details in Reservations (page coming soon).