Bestellung zurückmelden

Wir hängen an den Warenkorb-Link eine Kennung. Kommt es zum Kauf, meldet dein Shop die Bestellung an unseren Endpunkt, und die Vermittlung ist zugeordnet.

Was zu tun ist

Sag uns, welche Parameternamen dein Shop oder dein Affiliate-System erwartet, und übernimm die Werte aus dem Link in deine Bestellung. Fertig, wenn die Kennung nach einem Kauf in deinen Bestelldaten auftaucht.
Richte den Webhook auf https://choicera.com/api/webhooks/shopify ein, für die drei Ereignisse bezahlt, storniert und erstattet. Fertig, wenn eine Testbestellung bei uns ankommt und wir dir den Empfang bestätigen.
Stimm den Signatur-Schlüssel mit uns ab und signiere jede Anfrage damit. Fertig, wenn deine Zustellungen HTTP 200 bekommen und keine 401.

Kennungen im Link

Wir übergeben eine Affiliate-Kennung und eine Sub-Kennung, damit ein Kauf sowohl unserem Konto als auch der vermittelnden Stelle zugeordnet werden kann, etwa einem Fitnessstudio. Die Namen legen wir mit dir fest.

Wozu Beispiel Hinweis

Affiliate-Kennung ?ref=choicera Parametername und Wert kommen von dir.

Sub-Kennung &subref=studio-123 Je Warenkorb unterschiedlich. Vertraglich meist pro Bestellposition zurückzumelden.

Gutschein &coupon=CHOICERA Nur wenn dein Shop Codes über die URL einlöst.

Vorgangs-ID &attributes[choicera_attribution]=… Bei Shopify. Der Wert landet an der Bestellung und kommt im Webhook zurück.

Wozu	Beispiel	Hinweis
Affiliate-Kennung	`?ref=choicera`	Parametername und Wert kommen von dir.
Sub-Kennung	`&subref=studio-123`	Je Warenkorb unterschiedlich. Vertraglich meist pro Bestellposition zurückzumelden.
Gutschein	`&coupon=CHOICERA`	Nur wenn dein Shop Codes über die URL einlöst.
Vorgangs-ID	`&attributes[choicera_attribution]=…`	Bei Shopify. Der Wert landet an der Bestellung und kommt im Webhook zurück.

Arbeitest du mit einem Affiliate-Netzwerk, senden wir dessen Parameter, etwa ?clickref=…&clickref2=… bei Awin oder die programmeigene Referenz bei UpPromote. Sag uns, welches System zählt.

Ohne Vorgangs-ID ordnen wir eine Bestellung über die E-Mail-Adresse zu. Sie muss dann exakt der Adresse im Choicera-Konto entsprechen, einschließlich Groß- und Kleinschreibung.

Webhook einrichten

POST https://choicera.com/api/webhooks/shopify

Der Feldsatz folgt dem Shopify-Bestellformat. Shops ohne Shopify rufen denselben Endpunkt mit demselben Vertrag auf: gleiche Header, gleiche Feldnamen, gleiche Signatur. Vollständig als Datei: order-webhook.openapi.yaml (OpenAPI 3.1).

Ereignisse

Welches Ereignis gemeldet wird, steht im Header x-shopify-topic. Wir verarbeiten drei. Andere beantworten wir mit HTTP 200 und verwerfen sie.

Topic Bedeutung

orders/paid Bezahlte Bestellung mit den Bestelldaten

orders/cancelled Storno, macht die Zuordnung rückgängig

refunds/create Erstattung, meldet den erstatteten Betrag

Topic	Bedeutung
`orders/paid`	Bezahlte Bestellung mit den Bestelldaten
`orders/cancelled`	Storno, macht die Zuordnung rückgängig
`refunds/create`	Erstattung, meldet den erstatteten Betrag

Header

Header Bedeutung

x-shopify-topic Ereignisname, etwa orders/paid

x-shopify-hmac-sha256 Base64-kodierte HMAC-SHA256-Signatur über den unveränderten Request-Body. Fehlt sie oder ist sie ungültig, antworten wir mit HTTP 401.

x-shopify-webhook-id Eindeutige ID der Zustellung. Bei jeder Wiederholung derselben Zustellung derselbe Wert, nur so bleibt die Verarbeitung idempotent. Ein für ein anderes Ereignis wiederverwendeter Wert wird als Wiederholung behandelt. Fehlt die ID, nehmen wir die Zustellung an, sie ist dann aber nicht gegen Doppelverarbeitung geschützt.

x-shopify-shop-domain Shop-Domain, optional, hilft beim Suchen von Fehlern

Header	Bedeutung
`x-shopify-topic`	Ereignisname, etwa `orders/paid`
`x-shopify-hmac-sha256`	Base64-kodierte HMAC-SHA256-Signatur über den unveränderten Request-Body. Fehlt sie oder ist sie ungültig, antworten wir mit HTTP 401.
`x-shopify-webhook-id`	Eindeutige ID der Zustellung. Bei jeder Wiederholung derselben Zustellung derselbe Wert, nur so bleibt die Verarbeitung idempotent. Ein für ein anderes Ereignis wiederverwendeter Wert wird als Wiederholung behandelt. Fehlt die ID, nehmen wir die Zustellung an, sie ist dann aber nicht gegen Doppelverarbeitung geschützt.
`x-shopify-shop-domain`	Shop-Domain, optional, hilft beim Suchen von Fehlern

Der Signatur-Schlüssel wird beim Onboarding vereinbart und gilt nur für deinen Shop. Wir prüfen jede Zustellung gegen den Schlüssel des Shops, aus dem sie kommt, erkennbar am Header x-shopify-shop-domain. Ohne diesen Header oder mit einer uns unbekannten Shop-Domain antworten wir mit HTTP 401. Wir schalten die Anbindung frei, bevor sie live geht. Shopify-Shops legen die drei Ereignisse im Shopify-Admin unter Einstellungen, Benachrichtigungen, Webhooks auf unsere URL an.

Welche Felder wir auswerten

Feld Bedeutung

id Bestell-ID im Shop-System

order_number Menschenlesbare Bestellnummer

created_at Datum und Uhrzeit nach ISO 8601, ersatzweise processed_at

currency Währung, etwa EUR

total_price, subtotal_price, total_discounts Gesamtbetrag brutto, Zwischensumme vor Versand, Summe der Rabatte

discount_codes Eingelöste Gutscheincodes mit Betrag und Typ

email E-Mail der Käuferin, ersatzweise contact_email

note_attributes Enthält die Vorgangs-ID choicera_attribution aus dem Warenkorb-Link, falls eingerichtet. Wird nur zur Zuordnung ausgewertet, nicht gespeichert.

line_items Bestellpositionen mit product_id, variant_id, sku, title, variant_title, quantity als Zahl und price

Feld	Bedeutung
`id`	Bestell-ID im Shop-System
`order_number`	Menschenlesbare Bestellnummer
`created_at`	Datum und Uhrzeit nach ISO 8601, ersatzweise `processed_at`
`currency`	Währung, etwa `EUR`
`total_price`, `subtotal_price`, `total_discounts`	Gesamtbetrag brutto, Zwischensumme vor Versand, Summe der Rabatte
`discount_codes`	Eingelöste Gutscheincodes mit Betrag und Typ
`email`	E-Mail der Käuferin, ersatzweise `contact_email`
`note_attributes`	Enthält die Vorgangs-ID `choicera_attribution` aus dem Warenkorb-Link, falls eingerichtet. Wird nur zur Zuordnung ausgewertet, nicht gespeichert.
`line_items`	Bestellpositionen mit `product_id`, `variant_id`, `sku`, `title`, `variant_title`, `quantity` als Zahl und `price`

Bei orders/cancelled genügt die id der Bestellung. Bei refunds/create werten wir id, order_id und transactions aus. Summiert werden Transaktionen mit kind = refund sowie Einträge ohne kind. Andere Transaktionsarten also nicht mitsenden.

Was gespeichert wird

Wir speichern eine Bestellung nur, wenn sie einem noch offenen Choicera-Kauf zugeordnet werden kann: über die Vorgangs-ID aus dem Warenkorb-Link, gültig 48 Stunden ab Übergabe, oder über die E-Mail-Adresse eines Choicera-Kontos. Jede Zuordnung wird einmal verwendet. Eine zweite Bestellung mit derselben Kennung ohne neuen Choicera-Warenkorb wird verworfen.

Eine HTTP-200-Antwort bestätigt den Empfang, nicht die Speicherung. Bestellungen ohne Zuordnung werden verworfen. Gespeichert werden ausschließlich die oben aufgeführten Felder. Die Bestelldaten verbleiben dauerhaft bei Choicera als Kaufübersicht der Kundin, eine zeitablaufbedingte Löschung erfolgt nicht. Bei einer Löschanfrage nach Art. 17 DSGVO entfernt Choicera E-Mail-Adresse und Produktangaben. Abrechnungsdaten ohne Produktbezug bleiben für die Provisionsabrechnung und gesetzliche Aufbewahrungspflichten gespeichert.

Für die Nennung in deiner Datenschutzerklärung gibt es einen Textbaustein.

Antworten und Wiederholungen

Antwort Bedeutung

200 Empfang bestätigt

400 JSON-Body nicht lesbar

401 Signatur fehlt oder ist ungültig

5xx Fehler bei uns. Zustellung später mit derselben x-shopify-webhook-id wiederholen.

Antwort	Bedeutung
200	Empfang bestätigt
400	JSON-Body nicht lesbar
401	Signatur fehlt oder ist ungültig
5xx	Fehler bei uns. Zustellung später mit derselben `x-shopify-webhook-id` wiederholen.

Antwortet der Endpunkt dauerhaft mit webhook_not_configured, ist die Anbindung bei uns noch nicht freigeschaltet. Melde dich dann über den Partner-Kontakt, statt weiter zu wiederholen.