Website integration

Connect a museum website to go~mus - event calendar, direct registration, group requests, ticket shop. Architecture sketch, flow, links to the resources.

This page is the top-level view of four use cases almost every museum website needs. Per use case: what it is, what architecture has worked, the steps you take, and where the concrete endpoints and examples live.

For details, follow the links into the resource pages.

Prerequisites

  • Your instance URL - examples in the docs use demo.gomus.de.
  • API token - a public token suffices for master data and availability. For requests, direct bookings and multi-locale you need an authenticated API user with the right permissions. More under Authentication.
  • Caching strategy - master data daily, availability live. Mandatory. More under Best practices.

Use case 1: Event calendar

What it is. All public dates of a museum on a calendar or list on your website, each linking into the booking flow.

Architecture. The calendar is pre-rendered or server-side cached once a day; your website serves HTML/JSON, not the go~mus API directly. Live polling per visitor is not allowed.

Flow:

1. Fetch dates via GET /api/v4/calendar (aggregated days), GET /api/v4/events (events with embedded dates) or GET /api/v4/dates (individual dates). Which endpoint fits depends on your layout. Details in Events.

2. Render in the frontend - list, table or calendar widget. Filter by museum, special exhibition, audience, language.

3. Link each date - either into the go~mus shop (schema https://<instance>/#/product/event/<event_id>?date_id=<date_id>) or, if the date has registerable: true, an embedded widget (see Widgets).

Multilingual. To render DE and EN at once, one round trip instead of two: bracket form ?locale[]=de&locale[]=en. Requires an API user permission, see Multi-locale.

Pitfalls.

  • Dates without registerable: true are display-only, no booking link.
  • Do not forget cache invalidation - otherwise dates that have disappeared still show.
  • Default date range is narrow (today to end of month). For preview calendars set start_at and end_at explicitly.

Use case 2: Direct registration for individual seats

What it is. Visitors register on your website for a public guided tour or event, with or without payment.

Architecture. Two variants:

VariantWhenEffort
Embed the widget (recommended)Get live fast, no own order flowEmbed an iframe, done
Own flow over the APIFull visual control, customer data in your systemDays to weeks

Variant A: Widget. Iframe URL per date (https://<instance>/widget/event/<event_id>/date/<date_id>). Example repo: gomus-public-iframe-example. More in Widgets.

Variant B: API flow.

1. Fetch the date detail via Events: date detail, check seats.available.

2. Optional: reservation via Reservations, if the checkout can take a while.

3. Create the order via Orders with items: [{ type: "Event", attributes: { id: <date_id>, quantity: N } }].

4. Finalize the order with payment info or as Pay-By-Link, see Concepts: order finalize.

Tickets instead of events. For classic admission tickets (day, time slot, annual pass) the flow is analogous with ticket-specific capacity and reservation endpoints - see Tickets and Annual tickets.

Pitfalls.

  • The id in the Event order item is the date id (date_id), not the event id.
  • There is no top-level POST /api/v4/reservations - reservations live under their resource (tickets/reservations, events/reservations).
  • Order creation fails if your price calculation diverges from the server. Always pull prices from the master data call, do not compute yourself. Details in Best practices.

Use case 3: Group request

What it is. A school class, a travel group, a senior group - someone wants to request a tour, not buy a direct ticket. Consultation needed, date alignment, manual back-office workflow.

Architecture. A website form with all required fields, submit over HTTPS to your servers (not directly to go~mus, to keep the token safe), your servers proxy the call to POST /api/v4/requests.

Flow:

1. Form on your website with the required fields - participants, preferred date, contact details, school grade, language, notes.

2. Submit via Requests. Required fields depend on your instance.

3. Follow-up in go~mus - the museum team sees the request in the back office, asks follow-up questions, plans the programme, converts to a binding booking.

Pitfalls.

  • Form fields that need lookup ids (language, age group, school grade, category) get filled from go~mus Lookups, do not hard-code.
  • Validate emails on the client. go~mus checks too, but too late for good UX.
  • If your website already sends its own confirmation email, set skip_confirmation_email: true to avoid duplicates - see Requests.

Use case 4: Ticket shop

What it is. Visitors buy tickets in connection with your website. The question is not whether to integrate, but how deep.

Architecture.

VariantSetupMaintenanceVisualWhen this fits
A: Link to the go~mus shopHoursVery lowBreaks on clickLive fast, simple ticket structure, brand consistency not critical
B: Embed web componentsDays to weeksMediumSeamlessStrong brand, frontend capacity, high conversion expectations

Linking and web components are not exclusive. Main pages as web components, newsletters and third-party pages link to the standard shop - a common combo.

Variant A. Link schema: https://<instance>/#/product/ticket/<ticket_id> (analogous for events, tours, coupons). Nothing else to do, the shop handles selection, payment, confirmation and email.

Variant B. Custom elements <go-*> inside your website, fully styleable with your CSS. Full component list, page examples for tickets, time slots, cart, checkout, user account in Web components.