Wenn Sie schon einmal mit Apples Rückerstattungsprozess gearbeitet haben, sind Sie in der Dokumentation wahrscheinlich auf das 12-Stunden-Antwortfenster gestoßen. Was dabei nicht immer klar wird: wie man tatsächlich antwortet.
Die CONSUMPTION_REQUEST ist eine Benachrichtigung; die Antwort darauf ist ein Aufruf einer anderen API, mit einem eigenen Key und einem Body, dessen Struktur sich seit 2021 bereits zweimal geändert hat. Wir haben was die Benachrichtigung selbst enthält vor einiger Zeit bereits behandelt. Dies ist der Teil danach, wenn Sie tatsächlich antworten müssen.
Die wichtigsten Punkte
Es handelt sich um einen einzigen PUT-Request an die App Store Server API. Das ist der gesamte Mechanismus.
Jede Anfrage wird mit einem JWT signiert, das aus Ihrem In-App-Purchase-Key stammt; Tokens, die älter als 60 Minuten sind, werden abgelehnt.
Der v2-Body enthält fünf Felder, drei davon sind erforderlich.
Apple antwortet mit 202 und sonst nichts. Die Rückerstattungsentscheidung folgt später als separate Benachrichtigung.
Zwölf Stunden ab dem Zeitpunkt, an dem die Benachrichtigung eingeht, und innerhalb dieses Zeitfensters können Sie erneut senden.
Was ist eine Apple-Verbrauchsanfrage?
Eine Apple-Verbrauchsanfrage ist, hinter dem ganzen Fachjargon, im Kern eine Frage. Ein Kunde hat Apple um sein Geld zurück gebeten, und bevor Apple ihm antwortet, wendet sich Apple an Ihren Server und fragt: Hat diese Person das erhalten, wofür sie bezahlt hat, und hat sie es genutzt?
Apple verknüpft das, was Sie mitteilen, mit Informationen, die bereits vorliegen – etwa wie oft dieser Kunde Rückerstattungen beantragt –, und entscheidet eigenständig.
Diesen letzten Punkt verstehen viele ständig falsch. Sie genehmigen oder lehnen nichts ab – Sie liefern Fakten.
Die CONSUMPTION_REQUEST, die Apple sendet, geht als Server-Benachrichtigung der Version 2 an die Server-URL, die Sie in App Store Connect hinterlegt haben.
2021 wurde sie nur für Consumables ausgelöst. 2024 kamen Abonnements hinzu, und im Dezember 2025 veröffentlichte Apple Version 2 des Endpunkts, deren Dokumentation besagt, dass sie alle Produkttypen abdeckt – einschließlich Non-Consumables und nicht verlängerbarer Abonnements. Die Referenzseite für Benachrichtigungen listet weiterhin nur die ursprünglichen zwei auf; ich würde mich auf die neuere Seite verlassen und für alle vier entwickeln.
Und solange wir schon bei der Benennung sind: Viele suchen nach einer Apple Refund API, aber die gibt es nicht als eigenständige Sache. Dieser Aufruf ist Teil der App Store Server API.
Was Sie vor der Übermittlung benötigen
Drei dieser vier Punkte lassen sich nicht überstürzen – lesen Sie dies also vor Ihrer ersten Anfrage und nicht erst danach.
Der erste Punkt ist ein Key, genauer ein In-App-Purchase-Key, den Sie in App Store Connect unter „Nutzer und Zugriff" erstellen. Apple stellt Ihnen die .p8-Datei genau einmal zur Verfügung; außerdem benötigen Sie die zugehörige Key-ID und Ihre Issuer-ID.
Zweitens benötigen Sie eine Möglichkeit, von einer Transaktions-ID (die Apple Ihnen liefert) zu einer Person in Ihrer Datenbank (die Sie brauchen) zu kommen. Der saubere Weg dafür ist appAccountToken, der zum Zeitpunkt des Kaufs gesetzt wird und anschließend in jeder Benachrichtigung zu dieser Transaktion zurückkommt.
Falls Ihnen dieser Begriff neu ist, lesen Sie zuerst warum appAccountToken für die Rückerstattungsabwehr wichtig ist, denn ohne dieses Mapping ist der Rest dieses Beitrags rein theoretisch.
Drittens – und das ist der Punkt, der sich nicht um 2 Uhr nachts noch beheben lässt: die Einwilligung.
Apples Dokumentation sagt unmissverständlich: Wenn der Kunde nicht zugestimmt hat, dass Sie diese Daten weitergeben, antworten Sie gar nicht. Außerdem heißt es dort, in etwas juristischerer Sprache, dass die Gültigkeit der Einwilligung davon abhängt, wo Sie tätig sind, und dass Apple Sie dazu nicht beraten kann.
Opt-in-Formulierungen in Ihren Nutzungsbedingungen sind der übliche Weg, und sie müssen bereits vorhanden sein, bevor die Anfrage eintrifft.
Der vierte Punkt ist die Transaktions-ID selbst, die Sie erst erhalten, wenn die Benachrichtigung eintrifft und Sie Apples Signatur geprüft haben.
So übermitteln Sie Verbrauchsinformationen Schritt für Schritt
Die meisten, die nach send consumption information apple suchen, landen auf Apples Referenzseite, die die Felder aufzählt und dann recht abrupt endet. Hier ist der Ablauf in der Praxis.
Prüfen Sie zunächst, ob die Benachrichtigung echt ist. Die signedPayload ist ein JWS; Apples App Store Server Library verifiziert sie und liefert die decodierte Transaktion zurück, inklusive transactionId und appAccountToken.
Suchen Sie den Kauf auf Ihrer Seite. Worum es geht: Haben wir geliefert, welcher ungefähre Anteil wurde genutzt, hat der Kunde vorher ein Sample oder eine Testversion gesehen, und was würden wir uns von Apple wünschen.
Jetzt das Token. Header: alg ist ES256, kid ist Ihre Key-ID, typ ist JWT. Payload: iss ist Ihre Issuer-ID, iat ist der aktuelle Zeitpunkt, exp liegt maximal 60 Minuten später, aud ist der literale String appstoreconnect-v1, und bid ist Ihre Bundle-ID. Apples Leitfaden zum Erstellen von JSON Web Tokens enthält den genauen Aufbau, obwohl die Library das für Sie übernimmt.
Senden Sie den PUT-Request. Die Produktions-URL lautet https://api.storekit.apple.com/inApps/v2/transactions/consumption/{transactionId}, mit dem JWT als Bearer-Token im Authorization-Header, und einem Body in etwa wie folgt:
{
"customerConsented": true,
"deliveryStatus": "DELIVERED",
"consumptionPercentage": 94000,
"sampleContentProvided": false,
"refundPreference": "DECLINE"
}
Apple antwortet mit 202 Accepted, und das ist alles, was Sie bekommen. Protokollieren Sie Zeitpunkt, Body und Transaktions-ID, denn in einem Monat wird jemand fragen, was wir Apple zu diesem Fall mitgeteilt haben.
Dann warten Sie. Die Entscheidung kommt als REFUND- oder REFUND_DECLINED-Benachrichtigung. Bei REFUND entziehen Sie den Inhalt bzw. die Berechtigung noch am selben Tag.
Falls Sie sich also gefragt haben, wie man Verbrauchsinformationen übermittelt, die Apple tatsächlich verwendet: Das war's – eine Anfrage, fünf Felder, innerhalb des Zeitfensters.
Apple erlaubt es außerdem, innerhalb dieser 12 Stunden einen aktualisierten Payload zu senden – falls der erste Aufruf also nur mit halben Informationen rausging, senden Sie einfach einen zweiten.
Ein paar Dinge, die sich aus den Feldnamen allein nicht erschließen. consumptionPercentage wird in Milliunits angegeben, was häufig zu Verwirrung führt: 94000 bedeutet 94 Prozent, 100000 bedeutet alles, und der Wert muss 0 sein, wenn deliveryStatus etwas anderes als DELIVERED ist.
Die Optionen für „nicht geliefert" sind UNDELIVERED_QUALITY_ISSUE, UNDELIVERED_WRONG_ITEM, UNDELIVERED_SERVER_OUTAGE und UNDELIVERED_OTHER.
refundPreference ist optional und kann die Werte GRANT_FULL, GRANT_PRORATED oder DECLINE annehmen; bei GRANT_PRORATED für ein automatisch verlängerbares Abonnement lassen Sie den Prozentsatz weg, und Apple berechnet ihn anhand der verbleibenden Zeit.
Die Send Consumption Information Referenz enthält die vollständige Fehlerliste.
Was die Antwortcodes bedeuten
Es gibt genau eine gute Antwort: 202. Alles andere ist Apples Art, Ihnen mitzuteilen, was Sie falsch gemacht haben – meist namentlich.
Die 400er-Fehler sind am nützlichsten, da der Body den Fehler benennt.
ConsumptionPercentageOutOfRangeError bedeutet fast immer, dass jemand 94 statt 94000 gesendet hat.
UndeliveredConsumptionPercentageNonZeroError bedeutet, dass Sie angegeben haben, der Artikel sei nie angekommen, aber gleichzeitig behauptet haben, er sei teilweise genutzt worden.
InvalidCustomerConsentedError spricht für sich.
Ein 401 betrifft das Token: falscher Key, eine Ablaufzeit, die mehr als eine Stunde abweicht, eine nicht passende Bundle-ID oder eine Serveruhr, die so stark abweicht, dass iat wie ein Zeitpunkt in der Zukunft wirkt.
Ein 404 bedeutet, dass die Transaktions-ID nicht gefunden wurde, und meine erste Frage ist dabei immer, ob eine Sandbox-Transaktion an die Produktions-URL gesendet wurde (oder umgekehrt).
429 ist das Rate-Limit (50 Anfragen pro Sekunde und App in der Produktion, ein Zehntel davon in der Sandbox); lesen Sie den Retry-After-Header, bevor Sie es erneut versuchen.
500 liegt auf Apples Seite; versuchen Sie es später erneut.
So testen Sie es in der Sandbox
Das zu testen ist einfacher, als es klingt – mit einem Haken.
Hinterlegen Sie eine Sandbox-Server-URL in App Store Connect, melden Sie sich mit einem Sandbox-Apple-Account an, kaufen Sie etwas, öffnen Sie anschließend das Refund-Sheet Ihrer App (beginRefundRequest) und reichen Sie eine Anfrage ein.
Apples Testleitfaden für Rückerstattungsanfragen erklärt, wie sich die Testumgebung verhält: Wählen Sie einen beliebigen Grund, und die Rückerstattung wird automatisch genehmigt; wählen Sie Other und geben Sie DECLINE ein, wird sie abgelehnt; geben Sie GRANT_PRORATED ein, erhalten Sie eine anteilige Rückerstattung.
Der Haken steckt genau in diesen Regeln: Die Sandbox entscheidet anhand dessen, was Sie in das Sheet eingegeben haben, nicht anhand dessen, was Ihr Server gesendet hat – sie kann Ihnen also nicht sagen, ob Ihre Daten Apple in irgendeiner Weise überzeugen.
Testen lässt sich damit die technische Infrastruktur: Die Benachrichtigung kommt an, Ihr PUT an api.storekit-sandbox.apple.com liefert 202 zurück, und REFUND oder REFUND_DECLINED wird korrekt verarbeitet, wenn es eintrifft.
Außerdem versendet die Sandbox keine Rückerstattungs-E-Mails – warten Sie also nicht darauf.
Apple-Rückerstattungsautomatisierung: Wann Sie aufhören sollten, das manuell zu machen
Manuell erledigt bedeutet diese Aufgabe, dass jemand rund um die Uhr auf einen Alert wartet, eine Abfrage ausführt und fünf Felder absendet, bevor die 12-Stunden-Uhr abläuft.
Bei einer Handvoll Apple-Rückerstattungsanfragen im Monat ist das in Ordnung. Deutlich weniger in Ordnung ist es am ersten langen Wochenende, an dem niemand hinschaut.
Um Apple-Rückerstattungsanfragen zu automatisieren, nehmen Sie alles Vorangegangene und entfernen die Person aus der Mitte des Prozesses: Die Benachrichtigung trifft ein, Ihre Regeln verwandeln Liefer- und Nutzungsdaten in einen Payload, der Aufruf geht innerhalb von Minuten raus, die Entscheidung wird dem jeweiligen Fall zugeordnet protokolliert, und ein REFUND löst einen Entzug aus.
Das zu bauen ist kein großes Projekt; mit Apples Änderungen danach Schritt zu halten (etwa dem Wechsel von V1 zu v2) ist der Teil, der im Stillen immer wieder Aufwand verursacht.
Falls Sie das lieber nicht selbst machen möchten: Wir haben die dafür entwickelten Services in unserem Vergleich von Tools für das Apple-Rückerstattungsmanagement durchleuchtet, einschließlich wo Refund Sensor passt und wo nicht.
Ein Punkt, dem ich widerspreche, sobald er aufkommt: Apple-Rückerstattungsautomatisierung verändert, wie zuverlässig Sie antworten – nicht, wer entscheidet. Nichts in dieser API gibt einem Entwickler das letzte Wort.
Fazit
Der Aufruf selbst ist klein: ein signiertes Token, ein PUT, fünf Felder, ein 202 zum Protokollieren.
Was darüber entscheidet, ob es funktioniert, passiert an anderer Stelle: in der Einwilligung, die bereits in Ihren Nutzungsbedingungen steht, in einem appAccountToken bei jedem Kauf, in Nutzungsdaten, die Sie in Sekunden abrufen können, und in etwas, das um 3 Uhr nachts aufwacht, wenn die Benachrichtigung das auch tut.
Klären Sie diese Punkte, und es wird vom hektischen Gewusel zu etwas, das Ihr Server einfach erledigt.
Häufig gestellte Fragen
Es handelt sich um einen Endpunkt der App Store Server API, mit dem Sie auf eine CONSUMPTION_REQUEST antworten. Sie senden einen PUT-Request mit Verbrauchsdetails, und Apple antwortet mit 202 Accepted.
Sie haben 12 Stunden Zeit, gerechnet ab dem Eingang der CONSUMPTION_REQUEST. Apple erlaubt es, innerhalb dieses 12-Stunden-Fensters einen aktualisierten Payload zu übermitteln.
Ja. Apple erlaubt es, innerhalb des 12-Stunden-Fensters einen aktualisierten Payload zu senden. Das ist nützlich, wenn die erste Übermittlung unvollständig war.
Nein. Ein 202 Accepted bedeutet lediglich, dass Apple Ihre Informationen erhalten hat. Das Ergebnis folgt später als REFUND- oder REFUND_DECLINED-Benachrichtigung.
Ja. Das Feld customerConsented ist bei der Übermittlung von Verbrauchsinformationen erforderlich. Hat der Kunde nicht zugestimmt, besagt Apples Dokumentation, dass Sie nicht antworten sollen.
