Amazon SP-API Bestellbenachrichtigungen: wie Apps von einer neuen Bestellung erfahren

Was die Selling Partner API ist und was sie ersetzt hat

Jedes ernstzunehmende Werkzeug, das dein Amazon-Konto berührt, vom Repricer über den Buchhaltungsexport bis zur Bestellmelde-App, spricht mit derselben Stelle: der Selling Partner API, kurz SP-API. Eine App sieht dabei nur das, wofür du sie freigegeben hast.

Neu ist sie obendrein. Ihre Vorgängerin hieß Amazon Marketplace Web Service, kurz MWS. Amazon hat deren Ende im Seller Forum angekündigt: "SP-API will fully replace MWS, and we are migrating developers to SP-API as we work to deprecate MWS", also die SP-API ersetzt MWS vollständig. Dazu das harte Datum, MWS "will no longer be available after March 31, 2024". Wenn eine ältere Anleitung dir empfiehlt, MWS-Schlüssel zu erzeugen, beschreibt sie ein System, das es nicht mehr gibt.

Die eine Amazon Seller Central API gibt es nicht

Viele suchen nach "Amazon Seller Central API", als wäre das eine einzige Schnittstelle. Es ist eine Familie: eine Orders API für Bestellungen, eine Sales API für Tagesumsätze, eine Reports API für die Berichte, die du auch von Hand herunterladen kannst, eine Notifications API für Push-Nachrichten, eine Finances API für Transaktionen. Eine Bestellmelde-App braucht höchstens drei davon.

Die SP-API ist außerdem nach Regionen getrennt. Europa, Nordamerika und Fernost sind eigene Endpunkte mit eigenen Freigaben. Deshalb bittet eine App dich einmal für Europa und ein zweites Mal für Nordamerika um die Verbindung, wenn du in beiden Regionen verkaufst. Das ist der technische Grund hinter der Kontostruktur in Verkaufen auf mehreren Amazon-Marketplaces.

Was du freigibst, wenn eine App sich verbindet

Zugang bedeutet kein Passwort. Du landest auf einer Freigabeseite auf Amazons eigener Domain, siehst dort, welche Rollen die App anfragt, und tippst auf Confirm. Deine Zugangsdaten laufen nie durch die App.

Die Rollen sind der Teil, den man lesen sollte. Amazon beschreibt die Rolle, die eine Bestellmelde-App braucht, so: "The Inventory and Order Tracking role provides access to operations that analyze and manage inventory." Sie deckt das Lesen von Bestellungen und das Abonnieren von ORDER_CHANGE ab. Rollen, die Namen und Adressen von Käufern zeigen, sind eine eigene, eingeschränkte Kategorie mit strengerer Prüfung, und eine Meldungs-App hat keinen Grund, danach zu fragen.

Zwei Punkte, die Verkäufer selten hören. Die Freigabe ist nicht dauerhaft: Amazon schreibt, "the selling partner must reauthorize your public application every 365 days, or anytime you add a role to your application", die Verlängerung ist also jährlich fällig. Und du beendest sie in einer Minute in Seller Central unter Apps and Services, Manage Your Apps. Den ganzen Ablauf beschreibt wie du eine App sicher mit Seller Central verbindest.

ORDER_CHANGE: die Nachricht und die Warteschlange dahinter

Amazons Notifications API kennt rund zwei Dutzend Benachrichtigungstypen. Für Bestellungen zählt ORDER_CHANGE: "The ORDER_CHANGE notification is sent whenever there is an important change in the order. Important changes include order status changes and buyer requested cancelations." Sinngemäß: Die Nachricht kommt bei jeder wichtigen Änderung, dazu zählen Statuswechsel und Stornowünsche des Käufers. Den älteren Typ ORDER_STATUS_CHANGE gibt es zwar noch, Amazons eigenes Tutorial nennt ihn aber "deprecated" und verweist auf ORDER_CHANGE.

Bei der Zustellung liegen die meisten falsch. Amazon schickt für diesen Typ nichts an eine Webhook-Adresse deiner Wahl. Amazon schreibt in eine Amazon SQS Queue, eine Nachrichtenwarteschlange, die der App-Betreiber im eigenen Cloud-Konto anlegt und für die er Amazon Schreibrechte gibt. Amazons Einrichtungsseite führt ORDER_CHANGE unter den Typen auf, die so geliefert werden, und nennt eine Einschränkung, die viel über den Aufbau verrät: "Selling Partner API does not support delivery to FIFO queues. You must use Amazon SQS standard queues to receive notifications."

Standard-Warteschlangen können eine Nachricht mehrfach und in beliebiger Reihenfolge zustellen. Das ist normal, und deshalb merkt sich eine sorgfältige App jede bereits verarbeitete Benachrichtigungs-ID. Wenn eine App das Cha-Ching zweimal abspielt, liegt der Fehler meistens genau hier.

Was in der Nachricht steht und was fehlt

Die Nachricht ist kompakt und rund um die Bestellung gebaut, nicht rund um den Artikel. Amazon sagt es deutlich: "If you have multiple order items in the order, you will receive consolidated payloads at the order level." Eine Bestellung mit vier Produkten ergibt also eine Nachricht mit vier Einträgen, nicht vier Meldungen.

Es fehlt ausgerechnet das, was Verkäufer am meisten interessiert: kein Bestellwert, kein Einzelpreis, keine ASIN, kein Produkttitel. Amazons Solutions Architects beschreiben ORDER_CHANGE als Auslöser, um die vollständige Bestellung aus der Orders API zu holen, nicht als Ersatz dafür. Eine App, die dir einen Betrag zeigt, hat also einen zweiten Aufruf gemacht.

Dieser zweite Aufruf hat kurz nach der Bestellung eine Grenze. Amazon definiert Pending als "The order has been placed but payment has not been authorized", die Zahlung ist also noch nicht autorisiert. In diesem Zustand gilt: "the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions". Pending dauert meist etwa eine halbe Stunde, denn "the fulfillable date of an order is usually 30 minutes after the order has been created". Jeder Betrag in den ersten Minuten ist damit eine Schätzung. Wir zeigen ihn mit einem "≈" und aktualisieren ihn still, sobald Amazon die echte Zahl freigibt. Die Hintergründe stehen in was der Status Pending für Verkäufer bedeutet.

Ein Feld verdient eine Anmerkung: Die Nachricht enthält die Postleitzahl des Lieferziels, und Amazons Data Protection Policy zählt eine Postleitzahl zu den personenbezogenen Daten. Eine App, die keine Käuferdaten auf ihren Servern will, wirft dieses Feld weg, bevor irgendetwas gespeichert wird. Unsere tut das.

Warum FBA-Bestellungen im Status Pending still bleiben

Das ist der Teil, der nicht in der Dokumentation steht, weil wir ihn nur durch eine Messung auf unserem eigenen Verkäuferkonto gefunden haben.

Wenn Push dein einziger Kanal ist, erfährt ein FBA-Verkäufer also erst von einem Verkauf, wenn die Zahlung autorisiert ist. Auf unserem Konto waren das Stunden nach dem Klick des Käufers, keine Sekunden. Deshalb arbeiten wir mit drei Schichten, und zwar in der umgekehrten Reihenfolge zu den üblichen Architekturskizzen.

Die dritte Schicht ist nicht unsere Erfindung. Amazon verlangt sie: "As a best practice, we recommend that you have a means to retrieve needed information in the event of an unexpected outage or delay in notification delivery." Eine App ohne diesen zweiten Weg verliert irgendwann still eine Bestellung und sagt es dir nie. Wie sich die Schichten auf die Zeit bis zur Meldung auswirken, steht in wie schnell eine Amazon Bestellmeldung wirklich sein kann.

Was das für die Wahl einer App bedeutet

Du musst keine Zeile Code lesen, um eine Bestellmelde-App zu beurteilen. Vier Fragen trennen die sorgfältigen von den anderen.

1. Welche Schichten nutzt sie? Nur Push ist am billigsten zu bauen und genau der Weg, der bei FBA-Bestellungen in Pending stumm bleibt. Frag, ob zusätzlich abgefragt wird und wie oft.
2. Zählt sie, was sie verpasst hat? Ein zweiter Weg nützt nur, wenn das Ergebnis sichtbar ist. Unsere App zeigt die Zahl der verpassten Bestellungen, mit dem Ziel null.
3. Welche Rollen fragt sie an? Du siehst sie auf der Freigabeseite, bevor du bestätigst. Für die Meldung selbst reicht Inventory and Order Tracking; jede weitere Rolle sollte zu einer Funktion passen, die du nutzen willst. Wer bei einer Meldungs-App nach Käuferadressen fragt, ist ein Grund abzubrechen.
4. Was speichert sie? Die Nachricht enthält eine Postleitzahl, und Amazon behandelt die als Käuferdaten. Frag, ob sie verworfen wird und wie schnell alles gelöscht ist, wenn du die Verbindung trennst.

Wenn du noch abwägst, ob du überhaupt eine App von Dritten brauchst, beginne mit was die offizielle Amazon Seller App sendet und was nicht.