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 the bundleHours to daysLowSeamless (overlay/inline)Live fast, hosted by us, no order flow of your own, guest checkout is enough
C: Embed web componentsDays to weeksMediumSeamlessStrong brand, frontend capacity, accounts wanted, high conversion expectations

The three routes are ordered by effort and are not exclusive. Main pages as web components, the bundle on a campaign landing page, newsletters and third-party pages linking to the standard shop - all possible in parallel, same back office.

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. A single script tag embeds the complete go~mus booking, as an overlay or inline, hosted and maintained by us. No order flow of your own, guest checkout. Details: embed the bundle.

Variant C. 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.