Concepts

The go~mus API vocabulary explained in one go - instance, tenancy, master data vs live data, tokens, quotas, reservations, orders.

This page defines the terms you will keep seeing in the scenarios and reference. Read it through once, after that you only flip back.

Instance

go~mus is a web app that runs in the cloud. Each customer operates one or more instances (also called "hosts"). An instance has its own URL, usually a subdomain of gomus.de, in some countries also gomus.at, gomus.ch, gomus.be or gomus.lu.

Instance data pools are physically and logically separated. You always talk to one specific instance, never across.

Examples:

  • Single museum: foundation-a.gomus.de
  • Network with three sites: foundation-b.gomus.de
  • Network split by location: foundation-c-berlin.gomus.de and foundation-c-hamburg.gomus.de

The API is reachable on each instance at /api/v4.

Museum

Within an instance there is one or several museums. Tickets, tours and events are assigned to museums. Tokens can be limited to specific museums on an instance.

Locale / multilingual

Content can be served in multiple languages. The supported languages are configured at instance level. Use the locale query parameter to fetch one or several at once. Example: ?locale=de.

Master data vs live data

Two data categories with different update cadence:

  • Master data: descriptions, titles, images, prices (unless dynamic pricing). Rarely change. Cache once a day or once a season.
  • Live data: availability, free seats, quotas, start times. Query live right before booking or display, cache with care (short TTL).

Avoid sending direct live traffic for master data. A caching strategy is mandatory.

Public API vs Reseller API

The API has two areas:

  • Public: read-only. Accessible without authentication for some endpoints, others require auth.
  • Reseller: read and write. For distribution partners and booking platforms. Reseller tokens come with rate limits.

Both areas are documented in the OpenAPI spec.

Tokens and context awareness

go~mus tokens are context-aware. Meaning: the same endpoint returns different data or fields depending on the token. Example: a Reseller-A token sees only the tickets cleared for Reseller A. A User token sees the backend inventory.

Consequence:

  • Do not share tokens. Each external partner has its own.
  • Never expose tokens client-side (do not embed in browser JS). Hold server-side and proxy.
  • Send tokens with every request via Authorization: Bearer <token>.

Limited resources: quotas, capacities, seats

Tickets, tours and events are inherently limited. The mechanics differ per product type:

  • Quota: shared pool of seats that one or more tickets attach to. A booking only succeeds if there is room in all involved quotas.
  • Tickets: dedicated endpoints GET /api/v4/tickets/:id/capacity?date=YYYY-MM-DD and GET /api/v4/tickets/capacities for several tickets at once. The response lists time slots and bookable quantities.
  • Events: no separate capacity route. Availability sits directly in the date detail under seats.available (alongside seats.min, seats.max, seats.booked). Endpoint: GET /api/v4/events/:event_id/dates/:id.
  • Tours: availability via start times. GET /api/v4/tours/:id/start_times or GET /api/v4/tours/:id/start_times/:date.
  • Seating-plan events: in addition seat-level occupancy is available in the date detail under seatings.

Always run the right availability call before booking, otherwise you are flying blind.

Reservation

A short-term hold on a ticket without a final order. Keeps the seat for 5 minutes, refreshable up to a max of 60 minutes, so you can finish the booking flow at your pace.

  • Endpoint: POST /api/v4/tickets/reservations with payload { "reservation": { "ticket_id", "quantity", "start_at" } }
  • The response contains a token to be redeemed inside the order under attributes.reservations: [<token>].
  • Update / refresh: PUT /api/v4/tickets/reservations/:token
  • Combination tickets cannot be reserved.

Status: tickets are production-ready. For events a reservation mechanic exists (POST /api/v4/events/reservations); it is still work-in-progress and currently only supports public-tour bookings, full coverage on par with tickets is planned. Tours do not have their own reservations route; the availability conflict is resolved during request or order handling instead.

Recommended ticket flow: capacity check → reservation → create order and redeem reservation.

Recommended event/tour flow today: check date detail or start time → create order.

Order and order item

An order is the completed booking. It contains one or more order items (single products: ticket X, event Y, tour Z, donation, voucher).

When creating, you send your own price calculation along. The server checks against its own. If the values diverge, the server rejects. This safeguards against price manipulation and misconfigured discounts.

Order finalize

Creating an order is often not enough. With POST /api/v4/orders/:id/finalize you enrich it with customer, address and payment info and complete it. Only after finalize is the order confirmation sent and the ticket valid.

Special case of finalize: the order is created and finalized but marked as pay_by_link. The customer receives a payment link by email. If no payment arrives within X minutes, an automatic cancellation triggers. Useful when your system has no integrated payment, or when the customer should pay later.

Customers and foreign_id

Customers are people who triggered orders. If you operate your own CRM, attach a foreign_id (your ID) to the customer. On next access you identify via foreign_id instead of the go~mus ID. Benefit: no mapping table on your side.

The foreign_id should be as unique as possible (e.g. 16 random characters or a UUID).

Institutions

Even though orders are always triggered by a person, you can model institutions (school, association, company). Use addr_institution in the customer payload. The order then belongs to the institution and is discounted accordingly if a discount is configured.

Requests

Requests are non-binding precursors to bookings. Typical for group requests where consultation is needed before booking. POST /api/v4/requests creates a request. The follow-up (consultation, programme planning, binding booking) runs in the go~mus backend.

Tickets, tours, events

Three central product types:

  • Tickets: admission, day tickets, time slots, family tickets, annual passes.
  • Tours: group tours with consultation needs and programme planning.
  • Events: individual seat events with dates, often capacity-limited.

A product ID is unique in combination with instance and product type. Meaning: Ticket 3 on demo.gomus.de is not the same as Ticket 3 on another.gomus.de.

Seating maps

Events can have a seating map with rows, seats and price categories. Via API you can query the map, see free seats and book specific seats. Recommended: a workshop, the model goes a little deeper.

Barcodes and QR codes

Each ticket has a unique code, printed as 1D or 2D code (QR recommended). For individual visits one ticket equals one code. Group tickets can be issued with a single code for the whole group.

Data freshness: pull, not push

go~mus currently does not provide webhooks for data changes. There is no push from go~mus to your system when master data, contingents or orders change.

Recommended strategy:

  • Master data (tickets, events, tours, descriptions, images): poll once a day with pagination and cache.
  • Availability and capacities: query live, right before display or booking. Cache with care, short TTL.
  • Orders and requests: returned in the responses and can be queried live for a limited time after creation.

A mature pull-and-cache strategy is mandatory for production integrations. Direct live traffic on master data without a cache is rejected and will not get your integration into production.