Orders

Eine Order in go~mus ist die Bestellung - das Resultat einer Buchung über Tickets, Events oder Tours plus die zugehörigen Customer- und Payment-Daten. Das Anlegen einer Order ist auf den Resource-Seiten (Tickets, Events, Tours) bereits dokumentiert. Diese Seite klärt, was nach dem Create kommt: Listen, Suchen, Finalisieren, Stornieren - die typischen Aufgaben von Reseller-Portalen, Backoffice-Tools, Buchhaltungs-Integrationen.

Vollständige Endpoint- und Schema-Referenz: Swagger.

Lebenszyklus einer Order

   POST /orders
        │
        ▼
  ┌────────────┐    POST /orders/:id/finalize
  │  Created   │ ─────────────────────────────▶  ┌────────────┐
  │ (Entwurf)  │                                 │ Finalized  │
  └─────┬──────┘                                 │ (verbindl.)│
        │                                         └─────┬──────┘
        │                                               │
        ▼                                               ▼
  POST /orders/:id/cancellations              POST /orders/:id/cancellations
   (Storno einzelner Items oder ganz)           (Storno einzelner Items oder ganz)

Created: Order existiert, Items sind drin, Customer ggf. assoziiert. Kein Versand, kein Mailing, keine Zahlung registriert.

Finalized: Order ist verbindlich. Zahlung ist eingetragen, Bestätigungsmail (sofern nicht unterdrückt) ist raus, Tickets/Barcodes sind erzeugt. Ab hier ist die Order im Backoffice und in Reportings sichtbar.

Cancelled: Storniert - entweder einzelne order_items oder die ganze Order. Wichtig: das Stornieren aller Items macht die Order nicht automatisch zu einer cancelled Order; das ist ein eigener Aufruf.

Endpoints im Überblick

Endpoint	Wofür	Auth
`GET /api/v4/orders`	Liste eigener Orders, mit Datumsfilter	API-User mit Permission oder Customer
`GET /api/v4/orders/:id`	Order-Detail. `:id` kann numerische ID oder Order-Token sein	API-User oder Customer
`GET /api/v4/orders/barcode/:barcode`	Order über Ticket-Barcode finden	API-User mit Permission
`POST /api/v4/orders`	Order anlegen (siehe Events / Tours / Tickets)	abhängig vom Resource-Kontext
`POST /api/v4/orders/:id/finalize`	Two-phase Finalisierung (Reseller-Pattern)	API-User mit Permission
`PUT /api/v4/orders/:id/rate`	Bewertung setzen (nur Customer-Token)	Customer
`POST /api/v4/orders/:id/cancellations`	Order oder einzelne Items stornieren	API-User mit Permission
`GET /api/v4/orders/:order_id/tickets`	Ticket-Items dieser Order	API-User mit Permission
`GET /api/v4/orders/:order_id/events`	Event-Items dieser Order	API-User mit Permission
`GET /api/v4/orders/:order_id/tours`	Tour-Items dieser Order	API-User mit Permission
`GET /api/v4/orders/:order_id/coupons`	Coupon-Items dieser Order	API-User mit Permission
`GET /api/v4/orders/:order_id/invoices`	Rechnungs-Dokumente	API-User mit Permission

Hinweis: Order-show (GET /api/v4/orders/:id) liefert die Items bereits eingebettet im items-Array. Die Sub-Endpoints sind separat erreichbar, brauchen aber gegebenenfalls zusätzliche Permissions auf eurem API-User. Im Zweifel das eingebettete items aus dem Order-Detail nehmen.

Häufige Aufgaben

Eigene Orders auflisten

curl "https://demo.gomus.de/api/v4/orders?start_at=2026-04-01&end_at=2026-05-31&page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameter:

start_at, end_at - Filter über das Order-Erstellungsdatum (Default: letzte 30 Tage bis heute)
only_my_orders=true - nützlich für Cash-Point-User, die mehr als ihre eigenen Orders sehen können
valid=true - nur valide Orders
page, per_page - Pagination

Response enthält pro Order: ID, Created-At, Customer-Bezug, Items, Total, Status. Sortiere nach created_at DESC.

Order-Detail

curl "https://demo.gomus.de/api/v4/orders/MMW8KH..." \
  -H "Authorization: Bearer YOUR_TOKEN"

:id akzeptiert sowohl numerische IDs als auch Order-Tokens (Strings ab 18 Zeichen). Praktisch nach Create: du bekommst einen Token zurück, können direkt damit weiter arbeiten ohne ID-Lookup.

Order über Barcode finden

curl "https://demo.gomus.de/api/v4/orders/barcode/T123-456-789" \
  -H "Authorization: Bearer YOUR_TOKEN"

Resolved den Barcode auf das hinterliegende Ticket / Booking-Seat, dann auf die Order. Praktischer Use-Case: Service-Mitarbeiter:innen haben einen Ticket-Scan und wollen die zugehörige Bestellung im Reseller-Portal aufrufen.

Order finalisieren (Reseller Two-Phase-Pattern)

Reseller-Portale erstellen typischerweise zuerst eine "leere" Order, sammeln im UI Customer- und Payment-Daten, und fixieren das Ganze dann in einem zweiten Call:

curl -X POST "https://demo.gomus.de/api/v4/orders/ORDER_TOKEN/finalize" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "customer": {
        "foreign_id": "SF-12345",
        "name": "Schmidt", "surname": "Lukas",
        "email": "lukas@example.com",
        "language": "Deutsch",
        "addr_street": "Beispielallee 12",
        "addr_zip": "10115",
        "addr_city": "Berlin",
        "addr_country": "Deutschland"
      },
      "payment": {
        "payment_id": "PAY-9988-7766",
        "provider_id": "creditcard",
        "provider_name": "VISA",
        "message": "captured by reseller portal"
      },
      "completed": true
    }
  }'

Wichtig:

customer kann ein neues Customer-Objekt sein oder nur die foreign_id eines bereits in go~mus existierenden Customers (siehe Customers)
payment ist Reseller-Buchhaltung, nicht eine echte Charge - der Reseller hat das Geld bereits eingezogen, hier dokumentierst du nur den Vorgang
completed: true schließt die Order ab. Ohne (oder false) bleibt sie offen für weitere Updates.

Order stornieren

Komplette Order:

curl -X POST "https://demo.gomus.de/api/v4/orders/ORDER_ID/cancellations" \
  -H "Authorization: Bearer YOUR_TOKEN"

Nur einzelne Items:

curl -X POST "https://demo.gomus.de/api/v4/orders/ORDER_ID/cancellations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "order_item_ids": [12345, 12346] }'

Beim Item-Storno: andere Items bleiben aktiv, die Order selbst bleibt im Status "valid". Wer die ganze Order stornieren will, muss den ersten Aufruf machen, nicht alle Items einzeln.

Items einer Order

Order-show (GET /api/v4/orders/:id) liefert die Items bereits im items-Array - inklusive Tickets mit Barcodes, Event-Termine, Tour-Daten, Coupon-Codes. Für die meisten Anwendungsfälle reicht das.

Zusätzlich existieren typ-spezifische Sub-Endpoints (/orders/:id/tickets, /events, /tours, /coupons, /invoices), z.B. für Paginierung großer Orders. Diese Sub-Endpoints brauchen je nach Instanz und API-User-Konfiguration eigene Permissions; ohne diese kommen sie mit 422 not implemented/not found zurück. Im Zweifel mit dem eingebetteten items aus dem Order-Detail arbeiten.

Stolperdrahte

Order-Token vs ID. :id in den Routen akzeptiert beides. Nach Create hast du einst Token (≥18 Zeichen, String); spätestens nach Finalize hast du auch eine numerische ID. Beide funktionieren.
Finalize ist non-idempotent. Ein zweiter Finalize-Call auf derselben Order bringt einen Fehler. Im Code: nach Finalize den Token nicht wiederverwenden, order.completed lokal merken.
Storno aller Items ≠ Storno der Order. Wenn du alle Items einzeln stornieren wolltet, aber die Order selbst aktiv lassen wolltet (z.B. um neue Items hinzuzufügen, falls erlaubt), ist das ein anderer Fluss als "Order canceln". Die Doku im Source ist explizit: das automatische Cancel der Order bei null aktiven Items findet nicht statt.
only_my_orders=true ist relevant für Cash-Point-User. Default ist "alle Orders, die ich sehen darf". Wer nur die selbst angelegten will, setzt das Flag.
Barcodes müssen über die Customer-Mail-Bestätigung gegangen sein. Vor Finalize gibt es noch keinen Barcode - barcode/:barcode liefert dann 404. Bei Reseller-Two-Phase: erst nach Finalize barcoden.
rate nur für Customer-Token. Reseller- und Cash-Point-User können nicht im Namen von Customers raten - Bewertungen kommen ausschließlich vom Customer selbst.