Coupons

Ein Coupon in go~mus ist ein Wertgutschein - ein Produkt mit Verkaufspreis und einem Restwert, der nach dem Verkauf einlösbar ist. Coupons sind ein eigener Produkttyp parallel zu Tickets, Events und Tours: gleiche Order-Mechanik, eigener Endpoint für die Stammdaten.

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

Endpoints im Überblick

Endpoint	Wofür
`GET /api/v4/coupons`	Liste aller online buchbaren Coupons
`GET /api/v4/coupons/:id`	Detail eines Coupons inkl. Description und `content`

Anatomie eines Coupon-Objekts

id - stabiler Primärschlüssel, nutzt das in Order-Items
title - Titel im Index
description - im Detail-Response, Langtext für Detailseiten
price_cents - Verkaufspreis in Cent (was Käufer:innen zahlen)
value_cents - Restwert nach Verkauf in Cent (kann höher als price sein bei Aktionen)
vat_pct - Steuersatz
shipped_with_merchandise_id - falls gesetzt: ID des Merchandise-Artikels, der als Versandkosten-Repräsentation in derselben Order zu buchen ist
content (im Detail) - Multi-Locale-Inhalte für den Shop (shop_title, shop_sub_title, shop_description)

Häufige Aufgaben

Coupons auflisten

curl "https://demo.gomus.de/api/v4/coupons?locale=de"

Pagination via page und per_page wie bei den anderen Resourcen.

Coupon-Detail

curl "https://demo.gomus.de/api/v4/coupons/4?locale=de"

Coupon in eine Order einfügen

Coupon-Items folgen demselben Order-Schema wie Tickets:

{
  "items": [
    { "type": "Coupon", "attributes": { "id": 4, "quantity": 1 } }
  ]
}

Wenn der Coupon shipped_with_merchandise_id gesetzt hat, muss der zugehörige Merchandise-Artikel zusätzlich als Order-Item dazu, sonst kommt die Order ohne Versandkosten durch.

Beziehungen

Coupon
 ├── Merchandise ......... per shipped_with_merchandise_id (Versandkosten-Artikel)
 └── OrderItem ........... wenn verkauft, landet der Coupon als Item in einer Order

Stolperdrahte

price_cents ≠ value_cents. price ist was die Käufer:in zahlt, value ist was der Coupon nach Verkauf wert ist. Aktionen wie "50 € zahlen, 60 € einlösen" werden hier abgebildet - die Differenz ist Marketing-Marge, kein Bug.
Versandkosten via Merchandise. Wenn shipped_with_merchandise_id gesetzt ist, muss das referenzierte Merchandise-Item explizit zur Order hinzugefügt werden. Ohne sieht die Order kostenfrei aus, kommt aber beim Versand zu Bruch.