Skip to main content
Diese API befindet sich im Testing. Produktive Nutzung wird noch nicht empfohlen.

​
Definition

Tickets repräsentieren gebuchte ÖPNV-Fahrkarten. Business OS unterstützt sowohl Einzeltickets als auch Abonnements (z.B. Deutschlandticket). Der Lebenszyklus eines Tickets umfasst Erstellung, Aktivierung, optionale Verlängerung und Kündigung.

​
Ticket-Lebenszyklus

StatusBeschreibung
activeTicket ist gültig und nutzbar
cancelledAbo wurde gekündigt
expiredGültigkeitszeitraum ist abgelaufen

​
Ticket erstellen (CREATE)

Erstellt und aktiviert ein Ticket in einem atomaren Vorgang. Kostet 1 Credit.

​
Request Body

FeldTypPflichtBeschreibung
product_idstringjaID des gewünschten Produkts (aus /products)
customer_idstringneinKunden-ID für die Zuordnung
tariff_settingsobjectneinTarifspezifische Einstellungen (z.B. PLZ für Deutschlandticket)
identification_mediumobjectneinIdentifikationsmedium (z.B. Telefonnummer für VRS-Tickets)
{
  "id": "ticket-uuid",
  "organization_id": "org-uuid",
  "customer_id": "customer-uuid",
  "product_id": "prod_deutschlandticket",
  "product_name": "Deutschlandticket",
  "ticket_type": "subscription",
  "is_subscription": true,
  "coupon_id": "cpn_abc123",
  "ticket_id": "tkt_xyz789",
  "subscription_id": "sub_def456",
  "order_id": "ord_ghi012",
  "status": "active",
  "renewal_status": "pending",
  "current_cycle": 1,
  "valid_from": "2026-04-01T00:00:00.000Z",
  "valid_until": "2026-04-30T23:59:59.000Z",
  "price_in_cents": 4900,
  "created_at": "2026-03-27T10:00:00.000Z"
}
Bei einem teilweisen Fehler (z.B. Aktivierung schlägt fehl) wird eine partielle Response mit order_id und coupon_id zurückgegeben. Nutze den Activate-Endpoint, um die Aktivierung nachzuholen.

​
Ticket aktivieren (ACTIVATE)

Fallback-Aktivierung für teilweise fehlgeschlagene Erstellungen. Kostet keine Credits (bereits bei Erstellung bezahlt).

​
Request Body

FeldTypPflichtBeschreibung
coupon_idstringjaCoupon-ID aus der partiellen Response
tariff_settingsobjectneinTarifspezifische Einstellungen

​
Ticket verlängern (EXTEND)

Verlängert ein Abo-Ticket um einen weiteren Zyklus. Kostet 1 Credit. Nur für Subscriptions verfügbar. 
{
  "id": "ticket-uuid",
  "status": "active",
  "renewal_status": "renewed",
  "current_cycle": 2,
  "valid_from": "2026-05-01T00:00:00.000Z",
  "valid_until": "2026-05-31T23:59:59.000Z"
}

​
Ticket kündigen (CANCEL)

Kündigt ein Abo-Ticket. Kostet keine Credits. Nur für Subscriptions mit aktiver subscription_id verfügbar. 
{
  "id": "ticket-uuid",
  "status": "cancelled",
  "renewal_status": null
}

​
Tickets auflisten (READ)

Listet alle Tickets der Organisation auf. Unterstützt Filter.

​
Query-Parameter

ParameterTypBeschreibung
statusstringFilter nach Status (active, cancelled, expired)
is_subscriptionstringFilter nach Abo-Tickets (true / false)
customer_idstringFilter nach Kunden-ID

​
Ticket abrufen (READ)

Ruft die Details eines Tickets ab, inklusive Live-Status von der Mobility Box API. Abgelaufene Tickets werden automatisch auf expired gesetzt.

​
Wallet-Integration

Aktivierte Tickets können als Wallet-Passes heruntergeladen werden:

Apple Wallet

Gibt eine .pkpass-Datei zurück, die direkt zu Apple Wallet hinzugefügt werden kann.

Google Wallet

Gibt einen Save-Link zurück, über den das Ticket zu Google Wallet hinzugefügt werden kann.

​
Verbrauch

Für das Erstellen und Verlängern von Tickets wird jeweils 1 Credit berechnet. Alle Lese-Operationen und das Kündigen sind kostenfrei. Deinen detaillierten Verbrauch kannst Du in deinem Dashboard ansehen.