Bestelldaten für Shop Cash und Drittanbieter-Integrationen

Wenn Kund:innen bei einer Bestellung Shop Cash verwenden, wird Shop Cash als Zahlungsmethode behandelt. Es handelt sich nicht um einen Rabatt, Gutschein oder um Shop-Guthaben. Der verbleibende Bestellbetrag wird mit Shop Pay oder der Shop Pay-Ratenzahlung bezahlt.

Wenn Kund:innen beispielsweise 25 USD in Shop Cash bei einer Bestellung über 100 USD verwenden, enthält die Bestellung eine Shop Cash-Zahlung über 25 USD und eine Shop Pay-Zahlung über 75 USD. Deine Bestelldaten können für dieselbe Bestellung mehr als eine Zahlungsmethode enthalten.

Shop Cash wird als Bestelltransaktion mit dem Gateway-Wert shop_cash angezeigt, sofern Gateway-Werte verfügbar sind. Die Shop Cash-Transaktion folgt dem Standard-Lebenszyklus von Transaktionen, wie z. B. Autorisierung, Erfassung, Stornierung und Rückerstattung. Shop Cash verwendet keine kombinierte Verkaufstransaktionsart.

Wenn die Kund:in auch ein Shop-Angebot von Shop Campaigns nutzt, ist der kampagnenfinanzierte Wert in demselben Betrag der shop_cash-Bestelltransaktion enthalten. Die aus dem Käuferguthaben und die aus der Kampagne finanzierten Anteile werden nicht als separate Bestelltransaktionen dargestellt. Ab Januar 2026 werden Kampagnenkosten auf deiner Shopify-Rechnung abgerechnet, anstatt von deinen Auszahlungen abgezogen zu werden. Daher gelten Transaktionen für Kampagnenabrechnungen in der Auszahlungsaktivität nur für Kampagnen, die vor diesem Datum durchgeführt wurden. Weitere Informationen findest du unter Gebühren, Shop Campaigns und Shop Cash.

Drittanbietersysteme, die Bestellungen, Transaktionen, Zahlungen, Fulfillments, Rückerstattungen oder Rückgaben importieren, müssen Shop Cash als Zahlungsmethode erkennen. Wenn ein System Shop Cash nicht erkennt, können Bestellungen mit Shop Cash möglicherweise nicht importiert werden, werden mit unvollständigen Zahlungsdaten importiert oder erfordern eine manuelle Zuordnung.

Überprüfe die folgenden Anforderungen mit deinem Drittanbieter:

• Das System unterstützt mehr als eine Zahlungsmethode für eine Bestellung.
• Das System kann shop_cash als Zahlungsmethode zuordnen.
• Das System behandelt Shop Cash nicht als Rabatt, Gutschein oder Shop-Guthaben.
• Das System speichert die Bestelltransaktions-ID für jede Shop Cash-Autorisierung, -Erfassung, -Stornierung und -Rückerstattung.
• Das System speichert den vollständigen Shop Cash-Autorisierungswert, ohne ihn abzuschneiden, sofern der Wert in den vom System importierten Daten enthalten ist.
• Das System behandelt Autorisierungswerte als intransparente Strings und parst, decodiert, normalisiert, hasht oder leitet keine Bedeutung von ihnen ab.
• Das System kann Rückerstattungen verarbeiten, bei denen Beträge sowohl auf Shop Pay als auch auf Shop Cash erstattet werden.
• Das System kann Shop Cash-Auszahlungstransaktionen getrennt von Kartenzahlungstransaktionen abgleichen.
• Das System geht nicht davon aus, dass Transaktionen in einer bestimmten Reihenfolge zurückgegeben werden.

Wenn dein Drittanbietersystem davon ausgeht, dass jede Bestellung nur eine Zahlungsmethode hat, wende dich an den Anbieter, bevor du Shop Cash-Bestellungen über dieses System verarbeitest.

Der Autorisierungswert bei einer Shop Cash-Transaktion ist ein intransparenter String variabler Länge. Es handelt sich nicht um einen kurzen Karten-Autorisierungscode und ist nicht menschenlesbar.

Wenn dein ERP-, OMS- oder ein anderes Drittanbietersystem Shop Cash-Autorisierungswerte importiert, speichere den vollständigen Wert genau so, wie er bereitgestellt wird. Verwende nach Möglichkeit ein Textfeld mit variabler oder unbegrenzter Länge.

Befolge diese Richtlinien, wenn dein System Shop Cash-Autorisierungswerte speichert:

• Kürze den Wert nicht auf eine kurze, feste Länge wie 50 oder 100 Zeichen.
• Parse den Wert nicht und leite aus keinem Teil des Werts eine Bedeutung ab.
• Verwende den Autorisierungswert nicht, um Transaktionen für API-Vorgänge wie Erfassung, Stornierung oder Rückerstattung zu identifizieren.

Abgeschnittene Autorisierungswerte können dazu führen, dass Drittanbieterimporte oder die nachgelagerte Verarbeitung in ERP und OMS fehlschlagen.

Speichere Bestelltransaktions-IDs und übergeordnete Transaktionsbeziehungen, um Erfassungen, Stornierungen und Rückerstattungen über die Admin API zu unterstützen. Erfassungs- und Stornierungsvorgänge der Admin API identifizieren die Autorisierungstransaktion mit parentTransactionId. Rückerstattungsvorgänge identifizieren die erstattungsfähige Erfassungstransaktion mit parentId.

Wenn eine App oder Integration über die API eine Shop Cash-Rückerstattung veranlasst, muss die Rückerstattung der Shop Cash-Erfassungstransaktion untergeordnet sein, nicht der Shop Cash-Autorisierungstransaktion. Rückerstattungen für die Autorisierungstransaktion werden abgelehnt.

Rückerstattungs-Apps und Webhook-Handler sollten die erstattungsfähige Shop Cash-Erfassungstransaktion identifizieren, den verbleibenden erstattungsfähigen Betrag für diese Erfassung berechnen und die Rückerstattung anhand der Erfassungstransaktions-ID erstellen.

Wenn du die Admin API, Bestellexporte, Auszahlungsexporte oder Drittanbieter-App-Exporte verwendest, behandle Shop Cash als Zahlungsdaten. Je nach verwendetem Export oder verwendeter API-Ressource können Shop Cash-Informationen als Zahlungsmethode, Gateway, Bestelltransaktion, Auszahlungstransaktion und Rückerstattungsdaten dargestellt werden.

Wenn du eine Integration erstellst oder aktualisierst, speichere die folgenden Informationen für Bestellungen, die Shop Cash enthalten:

• Bestell-ID und Bestellname.
• Zahlungsmethode oder Gateway-Wert, wie beispielsweise shop_cash, sofern verfügbar.
• Bestelltransaktions-IDs für jede Zahlungstransaktion.
• Art und Status der Transaktion, wie Autorisierung, Erfassung, Rückerstattung oder Stornierung.
• Transaktionsbetrag und Währung.
• Beziehungen zur übergeordneten Transaktion, sofern verfügbar.
• Zahlungs-IDs, sofern verfügbar.
• Vollständige Autorisierungswerte, falls dein System diese importiert.
• Auszahlungs-IDs und Guthabentransaktions-IDs beim Abgleichen von Auszahlungen.
• Rückerstattungstransaktions-IDs beim Abgleichen von Rückgaben.

Weitere Details zu den verfügbaren Admin API-Feldern findest du in der Entwicklerdokumentation zur Admin API-Bestelltransaktion. Vermeide es, dich bei neuen Integrationen auf veraltete Felder wie OrderTransaction.authorizationCode zu verlassen.

Das folgende vereinfachte Beispiel zeigt eine Bestellung im Wert von 100 USD, bei der 75 USD über Shopify Payments und 25 USD über Shop Cash bezahlt wurden. Die Werte dienen nur zur Veranschaulichung.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash kann ähnlich wie andere Zahlungs- oder Aktionswerte aussehen, aber deine Systeme sollten jeden Wert separat behandeln:

Bevor du dich bei Bestellungen mit Shop Cash auf ein Drittanbietersystem verlässt, überprüfe die folgenden Anforderungen:

• Shop Cash ist als Zahlungsmethode zugeordnet.
• Bestellungen mit Shop Cash und Shop Pay werden mit beiden Zahlungsmethoden importiert.
• Die Logik der Zahlungsmethode geht nicht von einer Zahlungsmethode pro Bestellung aus.
• Autorisierungswerte werden als lange opake Strings gespeichert und nicht abgeschnitten.
• Die Rückerstattungslogik kann die richtige Erfassungstransaktion erstatten.
• Die Rückerstattungslogik kann Gelder auf die richtigen Zahlungsmethoden zurückerstatten.
• Der Auszahlungsabgleich kann Shop Cash-Gutschrifts-, Rückerstattungs- und Kampagnen-Transaktionsarten berücksichtigen.
• Fulfillment-, Buchhaltungs- und Rückgabe-Workflows behandeln Shop Cash nicht als Rabatt.

Wenn du mehrere Systeme verwendest, schließe diese Überprüfung für jedes System ab, das Bestell-, Transaktions-, Auszahlungs-, Fulfillment-, Rückerstattungs- oder Rückgabedaten empfängt.