Checkout-Zustände
Kostenlose Auto-Ausgabe gegenüber bezahltem Zahls-Checkout beim Erstellen von Bestellungen über die API
POST /orders erstellt einen Checkout für eine Veranstaltung. Erfordert orders:write und einen Idempotency-Key. Für bezahlte Totale muss die Organisation zahls.ch verbunden haben.
Antwort bei Bestellerstellung
Erfolgreiche Erstellung liefert 201 mit:
{
"order": { "id": "…", "status": "COMPLETED" },
"checkoutUrl": null,
"issuedTickets": [{ "id": "…", "code": "…" }]
}| Feld | Bedeutung |
|---|---|
order | Erstellte Bestellung (inkl. Positionen, Kunde, Payment Gateway falls relevant) |
checkoutUrl | Zahls-Zahlungs-URL für ausstehende bezahlte Bestellungen; sonst null |
issuedTickets | Bereits ausgegebene Tickets, wenn die Bestellung sofort abgeschlossen wurde; sonst [] |
Kostenlose oder vollständig rabattierte Bestellungen
Wenn der zahlbare Betrag 0 ist (kostenlose Tickets oder Rabatt auf 0):
- Die Bestellung wird automatisch abgeschlossen (
status: COMPLETED). - Tickets werden sofort ausgegeben.
checkoutUrlistnull.issuedTicketsenthält die ausgegebenen Tickets.- Zugehörige Webhooks wie
order.completed/ticket.issuedkönnen ausgelöst werden.
Keine Zahlungsweiterleitung nötig.
Bezahlte Bestellungen (Zahls)
Wenn der zahlbare Betrag grösser als 0 ist:
- Die Bestellung bleibt
PENDING, bis die Zahlung erfolgreich ist. checkoutUrlist eine Zahls.ch-Checkout-URL — leiten Sie die Kundin oder den Kunden dorthin weiter.issuedTicketsbleibt leer, bis die Zahlung abgeschlossen ist.- Nach erfolgreicher Zahlung werden Tickets ausgegeben und Abschluss-Webhooks ausgelöst.
Nutzen Sie GET /orders/{orderId} zum Polling oder abonnieren Sie Webhooks für den Abschluss.
Optional setzen Sie checkoutRedirectUrls (success, failure, cancel), damit Zahls Kundinnen und Kunden auf Ihren Shop statt auf Cowtics gehostete Seiten zurückführt. Siehe Headless-Checkout.
Physische Lieferung
Wenn die Veranstaltung physische Lieferung nutzt, senden Sie bei der Erstellung shippingAddress (street, zip, city, country). Fehlende Lieferdaten führen zu 400.
Stornierung
POST /orders/{orderId}/cancel erfordert orders:cancel. Bei bezahlten, abgeschlossenen Bestellungen kann ausserhalb des automatischen Stornopfads eine manuelle Rückerstattung nötig sein — prüfen Sie das Antwortflag requiresManualRefund.