Orders

Orders post-create - list, find (also by barcode), finalize in two phases, cancel. The lifecycle resellers and backoffice tools need.

An order in go~mus is the booking record - the result of a ticket, event or tour booking plus the associated customer and payment data. Order creation is documented on the resource pages (tickets, events, tours). This page covers what comes after create: list, find, finalize, cancel - the typical tasks of reseller portals, backoffice tools, accounting integrations.

Full endpoint and schema reference: Swagger.

Order lifecycle

   POST /orders
        │
        ▼
  ┌────────────┐    POST /orders/:id/finalize
  │  Created   │ ─────────────────────────────▶  ┌────────────┐
  │  (draft)   │                                 │ Finalized  │
  └─────┬──────┘                                 │ (binding)  │
        │                                         └─────┬──────┘
        │                                               │
        ▼                                               ▼
  POST /orders/:id/cancellations              POST /orders/:id/cancellations
   (cancel single items or whole order)        (cancel single items or whole order)

Created: order exists, items are in, customer associated if applicable. No shipping, no mail, no payment recorded.

Finalized: order is binding. Payment is recorded, confirmation email (unless suppressed) is sent, tickets and barcodes are generated. From here the order is visible in the back office and in reports.

Cancelled: cancelled - either single order_items or the whole order. Important: cancelling all items does not automatically cancel the order itself; that is a separate call.

Endpoints at a glance

EndpointWhatAuth
GET /api/v4/ordersList own orders, with date filterAPI user with permission or customer
GET /api/v4/orders/:idOrder detail. :id accepts numeric id or order tokenAPI user or customer
GET /api/v4/orders/barcode/:barcodeFind order via ticket barcodeAPI user with permission
POST /api/v4/ordersCreate an order (see events / tours / tickets)depends on resource context
POST /api/v4/orders/:id/finalizeTwo-phase finalize (reseller pattern)API user with permission
PUT /api/v4/orders/:id/rateSet rating (customer token only)Customer
POST /api/v4/orders/:id/cancellationsCancel order or individual itemsAPI user with permission
GET /api/v4/orders/:order_id/ticketsTicket items of this orderAPI user with permission
GET /api/v4/orders/:order_id/eventsEvent items of this orderAPI user with permission
GET /api/v4/orders/:order_id/toursTour items of this orderAPI user with permission
GET /api/v4/orders/:order_id/couponsCoupon items of this orderAPI user with permission
GET /api/v4/orders/:order_id/invoicesInvoice documentsAPI user with permission

Note: order show (GET /api/v4/orders/:id) already embeds the items in the items array. The sub-endpoints are reachable separately but may require extra permissions on your API user. When in doubt, use the embedded items from the order detail.

Common tasks

List own orders

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"

Parameters:

  • start_at, end_at - filter on order creation date (default: last 30 days to today)
  • only_my_orders=true - useful for cash-point users who can see more than their own orders
  • valid=true - valid orders only
  • page, per_page - pagination

Response contains per order: id, created_at, customer reference, items, total, status. Sorted by created_at DESC.

Order detail

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

:id accepts both numeric ids and order tokens (strings of length 18 or more). Handy after create: you get a token back and can keep using it without an id lookup.

Find order by barcode

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

Resolves the barcode to the underlying ticket / booking seat, then to the order. Useful: service staff has a ticket scan and wants the matching order in the reseller portal.

Finalize order (reseller two-phase pattern)

Reseller portals typically create an "empty" order first, collect customer and payment data in the UI, and lock it in via a second 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
    }
  }'

Important:

  • customer may be a new customer object or just the foreign_id of an existing customer in go~mus (see customers)
  • payment is reseller bookkeeping, not a real charge - the reseller already collected the money, here you only document the transaction
  • completed: true closes the order. Without it (or false) it stays open for further updates.

Cancel an order

Whole order:

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

Single items only:

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] }'

On item cancel: other items stay active, the order itself stays "valid". To cancel the whole order, make the first call - cancelling each item individually does not.

Items of an order

Order show (GET /api/v4/orders/:id) already returns the items in the items array - including tickets with barcodes, event dates, tour data, coupon codes. That covers most use cases.

Type-specific sub-endpoints (/orders/:id/tickets, /events, /tours, /coupons, /invoices) exist additionally, e.g. for paginating large orders. These need their own permissions depending on instance and API user setup; without them the response is 422 not implemented/not found. When in doubt, work off the embedded items from the order detail.

Pitfalls

  • Order token vs id. :id in routes accepts both. After create you have a token (≥18 chars, string); after finalize you also have a numeric id. Both work.
  • Finalize is non-idempotent. A second finalize on the same order returns an error. In code: do not reuse the token after finalize, remember order.completed locally.
  • Cancel all items ≠ cancel the order. If you cancel every item individually but want the order itself to stay active (e.g. to add new items where allowed), that is a different flow from "cancel order". The source is explicit: auto-cancelling the order when zero items remain does not happen.
  • only_my_orders=true matters for cash-point users. Default is "all orders I am allowed to see". For "only the ones I created", set the flag.
  • Barcodes need the customer mail confirmation step. Before finalize there is no barcode - barcode/:barcode returns 404. With reseller two-phase: barcode lookups only after finalize.
  • rate is customer-token only. Reseller and cash-point users cannot rate on behalf of customers - ratings come from the customer themselves.