easyReturns Benutzerhandbuch
Shopify Flow mit easyReturns verwenden
Zuletzt aktualisiert:
Mit Shopify Flow kannst du auf Ereignisse aus easyReturns reagieren, zum Beispiel eine Nachricht senden oder eine Bestellung kennzeichnen. Die Automation wird in Shopify Flow eingerichtet, nicht in den easyReturns-Einstellungen.
Voraussetzungen
- Shopify Flow ist für deinen Shop verfügbar und installiert.
- easyReturns ist im Shop installiert und authentifiziert.
- Der zugrunde liegende Retouren- oder Widerrufsworkflow ist eingerichtet.
Flow erstellen
- Öffne Shopify Flow im Shopify-Admin.
- Erstelle einen neuen Workflow.
- Wähle einen easyReturns-Trigger.
- Ergänze Bedingungen und die gewünschte Shopify-Flow-Aktion.
- Speichere und aktiviere den Workflow.
- Löse das Ereignis mit einem geeigneten Testvorgang aus.
- Prüfe Ausführung und Ergebnis im Shopify-Flow-Protokoll.
Verfügbare Ereignisse
easyReturns stellt Ereignisse für folgende Workflowphasen bereit:
- Retourenanfrage eingegangen,
- Retoure erstellt beziehungsweise genehmigt,
- Retoure abgelehnt,
- Retoure durch den Kunden storniert,
- Retoure geschlossen,
- Label erstellt,
- Wareneingang vollständig,
- Widerruf eingegangen,
- Widerruf genehmigt,
- Widerruf abgelehnt.
Welche Daten ein Trigger bereitstellt, siehst du bei seiner Auswahl in Shopify Flow.
Einheitliche Retouren-Trigger
Alle acht Retouren-Trigger verwenden dieselben Datenfelder. Bestehende Handles, Order-Referenzen, URLs und die bisherigen Felder unter Return bleiben erhalten.
| Trigger | Ausloeser |
|---|---|
Return requested (return-requested) |
Tatsaechlicher Wechsel zu REQUESTED, auch bei automatischer Genehmigung; bei Umwandlung eines Widerrufs erst nach vollstaendiger Artikelanlage |
Return created (return-created) |
Eine neue Shopify-Return-ID wird am Vorgang gespeichert |
Return approved (return-approved) |
Wechsel zu OPEN durch Genehmigung; Wiedereroeffnung desselben geschlossenen Returns ist keine erneute Genehmigung |
Return declined (return-declined) |
Wechsel zu DECLINED, mit gespeichertem Ablehnungsgrund |
Return closed (return-closed) |
Wechsel zu CLOSED, auch bei Abschluss durch Shopify und anschliessender Synchronisation |
Return canceled by customer (return-canceled-by-customer) |
Wechsel zu CANCELED_BY_CUSTOMER, getrennt von einer Haendlerablehnung |
Label created (label-created) |
Ein neues Label und gegebenenfalls sein QR-Code wurden erfolgreich gespeichert |
Goods Received - Wareneingang (goods-received) |
Die empfangenen Mengen wechseln von unvollstaendig zu vollstaendig |
Gemeinsame Retourendaten
| Feld | Inhalt |
|---|---|
| Order-Referenz | Shopify-Bestellung, in Flow als order verfuegbar |
Retoure / Bestellnummer |
Retouren-UUID / sichtbare Bestellnummer |
Status / PreviousStatus |
Neuer / vorheriger Retourenstatus; vor dem ersten Status ist der vorherige Wert leer |
EventType |
Trigger-Handle, beispielsweise label-created; unterscheidet auch Ereignisse mit demselben Status |
EventId / OccurredAt |
Ereignis-UUID / Zeitpunkt im ISO-8601-Format mit Zeitzone |
Email / Name |
Kunden-E-Mail / Kundenname aus den Bestellmetadaten, soweit vorhanden |
Datum / Uhrzeit |
Erstellungsdatum und -uhrzeit der Retoure |
Portal URL / App URL |
Kundenportal / Haendleransicht |
Ablehnungsgrund |
Gespeicherte Ablehnungs- beziehungsweise Kundenstornonotiz, sonst leer |
Return.shopifyId / Return.name |
Shopify-Return-GID / Retourenname, sofern bereits angelegt |
Return.comment / Return.images |
Kundenkommentar / hochgeladene Dateien mit url |
Return.items |
Artikel mit name, quantity, receivedQuantity, reason und returnOption |
Return.provider |
Eingestellter Rueckversandanbieter |
Return.trackingNumber / Return.trackingUrl |
Trackingdaten des Labels, soweit vorhanden |
Status-, Artikel-, Datei- und Trackingdaten bilden einen Snapshot des jeweiligen Ereignisses. Bei Label- und Wareneingangsereignissen bleibt Status normalerweise unveraendert; PreviousStatus entspricht dann Status.
Wichtige Unterschiede zur bisherigen Ausloesung
- Status-Trigger werden erst nach erfolgreichem Speichern und Datenbank-Commit versendet. Wiederholtes Speichern desselben Status sowie Rollbacks erzeugen kein weiteres Statusereignis.
- Return approved wird nicht mehr nochmals durch die Labelerstellung ausgeloest. Wenn ein Workflow auf ein verfuegbares Label angewiesen ist, verwende Label created. Bei der Genehmigung muss noch kein Label vorliegen.
- Return created und Return approved sind unterschiedliche Ereignisse und koennen beide bei demselben Genehmigungsvorgang auftreten. Abonniere fuer dieselbe externe Aktion nicht beide, wenn sie nur einmal ausgefuehrt werden soll.
- Der Wareneingangsjob wird erst nach Commit eingereiht, wartet weiterhin zehn Sekunden und prueft erneut, ob alle Artikel vollstaendig empfangen sind. Seine Daten, Ereigniszeit und Event-ID stammen bereits vom ausloesenden Mengenwechsel. Bei einer Wiederholung desselben Jobs bleibt die Event-ID erhalten.
- Eine neu vorgenommene vollstaendige Wareneingangsbuchung nach zwischenzeitlicher Mengenreduzierung ist ein neues Ereignis. Eine globale Exactly-once-Zustellung oder Reihenfolgegarantie besteht nicht; der Empfaenger muss
EventIdzur Deduplizierung verwenden. - Fuer Wiedereroeffnung, allgemeine Retourenaenderungen und Haendlerstornierung werden keine neuen Trigger eingefuehrt.
Retouren per HTTP weiterleiten
Die unten beschriebene Aktion Send HTTP request, ihre Tarifvoraussetzung und ihre Fehlerbehandlung gelten ebenso fuer Retouren. Waehle einen der oben genannten Retouren-Trigger und verwende beispielsweise diesen Body:
{
"event_id": {{ eventId | json }},
"event_type": {{ eventType | json }},
"occurred_at": {{ occurredAt | json }},
"return_id": {{ retoure | json }},
"order_id": {{ order.id | json }},
"status": {{ status | json }},
"previous_status": {{ previousStatus | json }},
"decline_reason": {{ ablehnungsgrund | json }}
}
Fuege weitere Artikel- und Trackingfelder ueber den Flow-Variablenwaehler hinzu. Shopify wandelt die Feldnamen fuer Liquid in camelCase um. Die erweiterten Extensions muessen zusammen mit dem Backend bereitgestellt und die Workflows im Testshop geprueft werden; die Bereitstellung ist unten beschrieben.
Widerrufsstatus an ein eigenes System senden
Die easyReturns-Trigger reichen aus, um einen externen Dienst per HTTP ueber die drei fachlichen Widerrufsstatus zu informieren. Eigene Shopify-Webhook-Themen fuer Widerrufe sind dafuer nicht erforderlich. Der Haendler abonniert ein Ereignis, indem er den entsprechenden Workflow in Shopify Flow aktiviert.
Tarifvoraussetzung: Shopify Flow und die Aktion Send HTTP request muessen verfuegbar sein. Laut Shopify ist diese Aktion nur in Grow, Advanced und Plus, nicht in Basic, enthalten. Diese Grenze betrifft den Shopify-Tarif, nicht den easyReturns-Tarif.
Abgleich mit Shopify-Return-Webhooks
Shopify-Returns und rechtliche Widerrufe sind unterschiedliche Vorgaenge. Die folgenden Entsprechungen sind fachliche Zuordnungen; easyReturns registriert damit keine neuen Shopify-Webhook-Themen.
| Shopify-Thema | Widerrufsphase | easyReturns-Flow-Trigger |
|---|---|---|
RETURNS_REQUEST |
Eingereicht: created → requested |
Withdrawal requested (withdrawal-requested) |
RETURNS_APPROVE |
Genehmigt: Wechsel zu approved |
Withdrawal approved (withdrawal-approved) |
RETURNS_DECLINE |
Abgelehnt: Wechsel zu declined |
Withdrawal declined (withdrawal-declined) |
RETURNS_CANCEL |
Kein eigener Widerrufsstatus | Kein entsprechender Trigger; Bestellstorno ist ein separater Vorgang |
RETURNS_CLOSE |
Kein eigener Widerrufsstatus | Ein genehmigter Widerruf wird nicht spaeter als Widerruf geschlossen |
RETURNS_REOPEN |
Kein eigener Widerrufsstatus | Kein eigener Wiedereroeffnungsprozess fuer Widerrufe |
RETURNS_PROCESS |
Retourenabwicklung, kein Widerrufsstatus | Gegebenenfalls Ereignisse der verknuepften Retoure verwenden |
RETURNS_UPDATE |
Allgemeine Aenderung, kein einzelner Status | Kein allgemeiner Widerrufs-Update-Trigger |
created ist ein noch nicht eingereichter Entwurf und loest keinen Trigger aus. Das Loeschen eines Entwurfs ist kein RETURNS_CANCEL. Eine spaeter aus einem Widerruf erzeugte Retoure hat einen eigenen Lifecycle.
Einheitliche Daten der drei Widerrufs-Trigger
Alle drei Trigger stellen dieselben Felder bereit. Bestehende Handles und Felder bleiben erhalten:
| Feld | Inhalt |
|---|---|
| Order-Referenz | Shopify-Bestellung, in Flow als order verfuegbar |
Widerruf |
Eindeutige UUID des Widerrufs |
Bestellnummer |
Sichtbare Bestellnummer |
Status / PreviousStatus |
Neuer / vorheriger Status, beispielsweise approved / requested |
EventId |
UUID dieses Statusereignisses, zur Deduplizierung beim Empfaenger |
OccurredAt |
Zeitpunkt des Statusereignisses im ISO-8601-Format mit Zeitzone |
Email / Name |
E-Mail-Adresse / Name des Kunden |
Datum / Uhrzeit |
Erstellungsdatum und -uhrzeit des Widerrufs, nicht des Statuswechsels |
URL |
Oeffentliche Detail-URL des Widerrufs |
Ablehnungsgrund |
Gespeicherter Ablehnungsgrund, sonst leere Zeichenfolge |
Withdrawal.reason / Withdrawal.comment |
Widerrufsgrund / Kundenkommentar |
Withdrawal.items |
Ausgewaehlte Artikel mit name und ganzzahliger quantity; Mengen von null werden nicht uebertragen |
Der interne Haendlerkommentar wird nicht uebertragen. Artikel und Kommentare sind ein Snapshot zum Zeitpunkt des jeweiligen Statuswechsels.
HTTP-Workflow einrichten
-
Erstelle einen Workflow mit easyReturns → Withdrawal requested.
-
Fuege die Aktion Send HTTP request hinzu.
-
Waehle POST und die HTTPS-URL deines eigenen Empfangsdienstes.
-
Setze
Content-Type: application/json. Falls dein Dienst einen Token verwendet, hinterlege ihn unter Flow → Settings → Secrets und verwende beispielsweiseAuthorization: Bearer {{secrets.easyreturns_endpoint_token}}. Verwende keine offen eingetragenen Zugangsdaten. -
Fuege die benoetigten Triggerdaten ueber Variable hinzufuegen in den Body ein. Beispielsweise:
{ "event_id": {{ eventId | json }}, "occurred_at": {{ occurredAt | json }}, "withdrawal_id": {{ widerruf | json }}, "order_id": {{ order.id | json }}, "status": {{ status | json }}, "previous_status": {{ previousStatus | json }}, "decline_reason": {{ ablehnungsgrund | json }} }Shopify Flow wandelt die Feldnamen fuer Liquid-Variablen in camelCase um. Nutze die von Flow im Variablenwaehler erzeugten Pfade, falls die Darstellung abweicht. Der
json-Filter sorgt fuer korrektes Escaping, insbesondere bei Anfuehrungszeichen und Zeilenumbruechen. Uebertrage Kundendaten und Artikel nur, wenn dein Empfangsdienst sie benoetigt. -
Konfiguriere die Fehlerbehandlung: beispielsweise bei
5xxund429Retry, bei permanenten4xxFail. Die Aktion wartet maximal 30 Sekunden auf eine Antwort; bei entsprechender Konfiguration wiederholt Shopify fehlgeschlagene Requests bis zu 24 Stunden. -
Aktiviere den Workflow und pruefe ihn mit einem Testwiderruf im Flow-Ausfuehrungsprotokoll und deinem Empfangsdienst.
-
Wiederhole die Einrichtung fuer Withdrawal approved und Withdrawal declined. Alle drei koennen dieselbe Empfangs-URL und denselben JSON-Aufbau verwenden.
Der Empfaenger sollte nach Annahme schnell mit 2xx antworten und wiederholte Zustellungen anhand von event_id idempotent verarbeiten. Eine erneute fachliche Statusaenderung desselben Widerrufs erhaelt eine neue Event-ID. Die zeitliche Reihenfolge der externen HTTP-Zustellung ist nicht garantiert.
Ausloeseverhalten und Bereitstellung
- Der Trigger entsteht erst nach erfolgreichem Speichern und Datenbank-Commit des Statuswechsels. Ein Rollback loest keinen Flow aus.
- Erneutes Speichern desselben Status oder Aenderungen nur an Kommentaren loesen keinen weiteren Status-Trigger aus.
- Eine automatische Genehmigung erzeugt sowohl Withdrawal requested als auch Withdrawal approved, jeweils mit eigenem Status-Snapshot. Scheitert die Genehmigung, entsteht nur Withdrawal requested.
- Es werden keine Ereignisse fuer bereits vorhandene historische Status nachgesendet.
- Die erweiterten Flow-Extensions muessen zunaechst mit Shopify CLI gegen die Test-App geprueft und anschliessend zusammen mit dem Backend veroeffentlicht werden. Fuer Produktion ist die Konfiguration
shopify.app.prod.tomlvorgesehen; der Release erfolgt nach Freigabe mitshopify app deploy --config prod. Erst danach stehen die neuen Felder in produktiven Workflows zur Verfuegung. Vorhandene Workflows behalten ihre bisherigen Felder; zusaetzliche Daten muessen in ihren Aktionen ausgewaehlt werden. - Der lokale Queue-Dispatch ist automatisiert getestet. Die reale Ausfuehrung in Shopify Flow und die Zustellung an den Haendler-Endpunkt muessen nach dem Extension-Deployment im Testshop geprueft werden.
Shopify-Referenzen
- Send HTTP request: Tarife, Fehlerbehandlung und Secrets
- Shopify-Webhook-Themen
- Flow-Trigger erstellen und veroeffentlichen
Wichtige Hinweise
- Kundenbenachrichtigungen von easyReturns und Shopify Flow sind getrennte Systeme. Beide können auf denselben Statuswechsel reagieren.
- easyReturns stößt den Trigger an; Ausführung, Bedingungen, Aktionen und Protokolle liegen anschließend bei Shopify.
- Plane Flow-Aktionen so, dass eine wiederholte Ausführung keine unerwünschten Folgen hat.