senn-techSnipcart-Versand-API: die Quelle der Wahrheit
Ein Kunde bestellt Ware, die palettiert verschickt werden muss. Die Versandseite nennt einen Preis, der Warenkorb im Checkout einen anderen, und die Produktseite hat noch eine dritte Zahl stehen. Drei Systeme, drei Antworten auf dieselbe Frage. Keines davon war offensichtlich falsch, weil jedes für sich genommen konsistent war. Genau das ist bei unserem eigenen Online-Shop bei senn-gruppe.com passiert, und die Suche nach der eigentlichen Wahrheit hat uns zu einer Snipcart-API geführt, die es offiziell gar nicht gibt.
Der Fall: vier Systeme, eine Sendung
Der Shop läuft auf Snipcart als Checkout-Layer über einem Kirby-Frontend, Headless Commerce in Reinform: die Inhalte liegen im CMS, die eigentliche Preisberechnung liegt bei Snipcart, und beide wissen im Normalfall nichts voneinander. Das funktioniert so lange gut, wie niemand eine Zahl an zwei Stellen pflegt. Bei den Versandkosten war das nicht der Fall: Der Preis stand in der Versand-Infoseite, im Produkt-Tab „Versandinformationen", im strukturierten Daten-Markup für die Suchmaschinen und schließlich in Snipcart selbst, das am Ende tatsächlich abrechnet. Vier Stellen, eine Zahl, jedenfalls in der Theorie. Praktisch war die Seite über Monate nicht mehr synchron mit dem, was der Warenkorb wirklich verlangte.
Das ist kein Snipcart-spezifisches Problem, sondern die Grundgefahr jeder Architektur, die Inhalt und Commerce-Logik trennt: Nichts im System zwingt die beiden Seiten, sich einig zu bleiben. Ein CMS-Redakteur ändert eine Zahl auf der Seite, ohne zu wissen, dass Snipcart eine eigene, unabhängige Kopie führt. Und umgekehrt.
Die Versandarchitektur, die die Website nicht zeigt
Bevor wir die Abweichung reparieren konnten, mussten wir erst verstehen, wie kompliziert unsere eigene Versandlogik tatsächlich ist. Die Antwort: deutlich mehr, als die Website andeutet. Insgesamt pflegt unser Shop 15 Versandmethoden: zwei klassische, gewichtsgestaffelte Paketmethoden für Inland und Nachbarland mit Staffeln bis in den dreistelligen Kilogrammbereich und einem Mindestbestellwert, dazu dreizehn weitere Methoden für Palettenfracht, gestaffelt nach Zustellzone und Gewicht bis mehrere hundert Kilogramm pro Palette. Die Website erklärt im Normalfall nur die erste Kategorie ausführlich, weil sie den typischen Kaufvorgang bedient. Die zweite existiert für das Geschäft mit größeren, palettierten Mengen und muss genauso korrekt sein, obwohl sie kaum jemand liest, bevor er bestellt.
Diese Komplexität von Hand im Snipcart-Dashboard zu prüfen (15 Methoden einzeln aufklappen, Staffeln vergleichen, Werte gegenrechnen) ist genau die Art Aufgabe, bei der ein Mensch nach der fünften Methode nicht mehr zuverlässig ist. Also haben wir uns die Frage gestellt, ob es einen Weg gibt, die tatsächlich aktive Konfiguration maschinell auszulesen.
Eine API, die niemand dokumentiert
Es gibt ihn. Snipcart veröffentlicht offiziell nur das Checkout-SDK und die Bestell-Webhooks, aber GET https://app.snipcart.com/api/shipping_methods liefert, authentifiziert per HTTP-Basic-Auth mit dem Secret Key als Benutzername und leerem Passwort, die vollständige Liste aller aktiven Methoden inklusive der Gewichtsstaffeln in Gramm. Derselbe Endpunkt akzeptiert auch PUT auf eine einzelne Methoden-ID mit dem vollständigen Methoden-JSON und übernimmt die Änderung sofort, ohne Umweg über das Dashboard. In der offiziellen Snipcart-Dokumentation taucht der Pfad nicht auf; andere Schreibweisen liefern 404, eine Anfrage ohne gültigen Key liefert 401. Beides zusammen ist der verlässlichste Beweis, den man für einen echten, aber unbeworbenen Endpunkt bekommen kann.
Der praktische Wert liegt nicht im Umgehen der Benutzeroberfläche, sondern in der Wiederholbarkeit: Ein einzelner GET-Aufruf zeigt in Sekunden, was Snipcart aktuell wirklich berechnet, über alle 15 Methoden hinweg, maschinenlesbar und diff-fähig gegen die vorherige Version. Das macht aus einer manuellen Sichtprüfung eine Zeile Code, die man bei jedem Zweifel erneut laufen lassen kann.
Merchant Center als Schiedsrichter
Damit war das technische Auslesen gelöst, aber nicht die eigentliche Frage: Wenn zwei Zahlen im Umlauf sind (eine ältere auf der Seite, eine neuere in Snipcart), welche ist richtig? Die Antwort kam nicht aus dem Shop selbst, sondern von außen: Google Merchant Center, das über die Merchant-API die aktive Versandkonfiguration (shippingSettings) trägt, mit der Google Shopping-Anzeigen und die organische Produktsuche tatsächlich rechnen. Diese Zahl kann sich niemand aus Versehen erlauben falsch zu haben, weil sie direkt an Kundinnen und Kunden in der Google-Suche ausgespielt wird und bei Abweichung zu Konto-Sperren im Werbebereich führen kann.
Eine Live-Abfrage der Merchant API gegen unser eigenes Konto zeigte eindeutig, welche der beiden im Shop kursierenden Zahlen mit dem übereinstimmte, was Google seit Langem von uns kennt, und damit, welche Version Website und Snipcart eigentlich zeigen sollten. Das war die Erkenntnis, die den Fall gelöst hat: In einer Multi-System-Architektur ist nicht automatisch die zuletzt geänderte Zahl die richtige. Die richtige Zahl ist die, an der sich ein außenstehendes System orientiert, das sich einen Fehler nicht leisten kann.
Der Abgleich als Prozess, nicht als Einmalaktion
Aus dem Vorfall ist eine Reihenfolge geworden, die wir jetzt bei jeder Versandänderung anwenden: zuerst Merchant Center per API abfragen (die externe Wahrheit), dann Snipcart per GET gegenprüfen (was der Checkout aktuell abrechnet), bei Abweichung per PUT korrigieren, anschließend die Handvoll CMS-Textstellen nachziehen, die dieselbe Zahl in Prosa wiederholen, den Seiten-Cache leeren und zum Schluss erneut per API verifizieren, dass alle vier Stellen wieder übereinstimmen. Jeder einzelne Schritt ist trivial; die Reihenfolge ist der Teil, der eine erneute Drift verhindert.
Was das für einen eigenen Shop bedeutet
Die Lehre lässt sich nicht auf Snipcart oder auf Versandkosten begrenzen. Sobald ein Shop aus mehreren unabhängigen Systemen besteht (Content-Management, Checkout-Anbieter, Werbe-Feed, strukturierte Daten für Suchmaschinen), ist eine Abweichung zwischen ihnen keine Frage des Ob, sondern des Wann. Zwei Dinge zahlen sich in jedem Projekt aus, das wir für einen Shop aufsetzen: erstens eine bewusste Entscheidung, welches System im Zweifel recht hat, statt das implizit dem letzten Bearbeiter zu überlassen; zweitens die Suche nach einem programmatischen Lesezugriff auf jedes beteiligte System, dokumentiert oder nicht, weil genau der die Abweichung in Minuten statt erst bei der nächsten Kundenbeschwerde sichtbar macht. Und wer neben Paketware auch größere, palettierte Sendungen führt, sollte die Versandlogik von Anfang an für diese Komplexität planen. Sie nachträglich in ein bestehendes System einzuziehen ist genau der Moment, in dem Seite und Warenkorb auseinanderlaufen.
Fazit
Vier Systeme, eine Zahl, und am Ende hat uns eine undokumentierte API und ein externer Datenfeed geholfen, herauszufinden, welche Zahl tatsächlich stimmt. Das ist der Unterschied zwischen einem Shop, der irgendwie läuft, und einem, dessen Versandkosten überprüfbar korrekt sind. Genau diese Art Integrationsarbeit gehört zu dem, was wir für Websites und Online-Shops anbieten: Systeme so bauen und verdrahten, dass sie sich nicht heimlich widersprechen.
Weiterführende Quellen
Was ist an der Snipcart-Versand-API besonders?+
Snipcart dokumentiert öffentlich nur das Checkout-SDK, nicht die Verwaltung der Versandmethoden selbst. Es gibt aber einen funktionierenden Endpunkt, GET und PUT auf /api/shipping_methods, der mit dem Secret Key als Basic-Auth-Benutzername authentifiziert wird und die komplette Methodenliste inklusive Gewichtsstaffeln zurückgibt beziehungsweise übernimmt. Er taucht in keiner offiziellen Doku auf, reagiert aber korrekt auf gültige und ungültige Anfragen. Er existiert, er ist nur nicht beworben.
Warum ist Google Merchant Center die Quelle der Wahrheit, nicht die eigene Website?+
Weil eine Website-Seite nur zeigt, was jemand zuletzt eingetragen hat, während Merchant Center die Versandkonditionen trägt, die tatsächlich in Google-Shopping-Anzeigen und in der organischen Produktsuche an Kundinnen und Kunden ausgespielt werden. Eine Abweichung dort schadet dem Vertrauen und wird von Google selbst als Regelverstoß gewertet. Damit ist der Merchant-Feed der Wert, an dem sich alle anderen Systeme messen lassen müssen, nicht umgekehrt.
Wie viele Versandmethoden braucht ein Shop wirklich?+
Sobald ein Shop neben Paketware auch palettierte Fracht verschickt, reicht eine einzelne Versandpauschale nicht mehr. Unser eigener Shop führt 15 Methoden: zwei gewichtsgestaffelte Paketmethoden für die üblichen Bestellgrößen und dreizehn weitere, gestaffelt nach Zustell-Zone, für Palettenware bis mehrere hundert Kilogramm. Die Website zeigt davon meist nur die erste Kategorie, weil sie den Normalfall bedient. Die zweite existiert trotzdem und muss genauso stimmen.
Wie lässt sich Versandkosten-Drift in einem Headless-Shop grundsätzlich vermeiden?+
Indem man festlegt, welches System die Wahrheit trägt, und die übrigen Stellen (Produktseite, Infoseite, strukturierte Daten, Werbe-Feed) regelmäßig automatisiert dagegen prüft, statt sie unabhängig voneinander von Hand zu pflegen. Ein einzelner Lesezugriff auf eine API reicht oft, um eine Abweichung in Minuten statt erst bei der nächsten Kundenreklamation zu finden.