Was ein CONSUMPTION_REQUEST ist, lässt sich in einem Absatz erklären. Etwas zu bauen, das ihn zuverlässig verarbeitet, dauert deutlich länger – und die Stolpersteine liegen nicht dort, wo man sie erwartet.
Die Signaturprüfung ist einer davon. Die Einwilligung ein weiterer, denn sie muss bereits vorliegen, bevor die Benachrichtigung eintrifft. Und der Retry-Zeitplan greift auf eine Weise in das Antwortfenster ein, die die meisten Teams überrascht, wenn sie ihn zum ersten Mal genau betrachten.
Dieser Beitrag führt durch den Handler – von dem Moment, in dem die Anfrage Ihren Endpunkt erreicht, bis zum Entitlement-Update, das den Vorgang abschließt.
Das Wichtigste in Kürze
• Ein CONSUMPTION_REQUEST fragt während einer Erstattungsprüfung Informationen ab. Die Entscheidung trifft weiterhin Apple.
• Prüfen Sie die signierte Payload, bevor Sie darauf reagieren. Vertrauen Sie niemals einer ungeprüften Benachrichtigung.
• Die Einwilligung muss bereits in Ihrer App vorliegen. Nach Eingang der Anfrage lässt sie sich nicht mehr einholen.
• Apple erwartet eine Antwort innerhalb von 12 Stunden nach der Benachrichtigung.
• Apple wiederholt fehlgeschlagene Zustellungen nach einem festen Zeitplan – der zweite Wiederholungsversuch trifft erst nach Ablauf des Antwortfensters ein.
• Verfolgen Sie das Ergebnis und aktualisieren Sie anschließend das Entitlement. Mit der Antwort ist der Vorgang nicht abgeschlossen.
Was ist eine Apple CONSUMPTION_REQUEST-Benachrichtigung?
Eine Apple CONSUMPTION_REQUEST-Benachrichtigung ist eine App Store Server Notification, die Ihrem Server mitteilt, dass ein Kunde eine Erstattung beantragt hat und Apple Sie einlädt, Verbrauchsinformationen zu diesem Kauf zu senden. Sie trifft an der von Ihnen konfigurierten Notification-URL ein, enthält die betreffende Transaktion und gibt Ihnen nur begrenzt Zeit für eine Antwort.
Sie ist weder eine Erstattung noch eine Entscheidung. Apple befindet sich mitten in einer Prüfung und sammelt Kontext. Ihre Aufgabe ist es, korrekte Informationen darüber zu liefern, was mit dem Kauf passiert ist; Apples Aufgabe ist es, zu entscheiden.
Warum sendet Apple einen CONSUMPTION_REQUEST?
Weil Apple nicht in Ihre App hineinsehen kann. Apple kennt die Transaktion, den Account und die Kaufhistorie. Apple weiß aber nicht, ob der Inhalt geliefert wurde, ob er funktioniert hat oder wie viel davon der Kunde genutzt hat.
Verbrauchsinformationen schließen diese Lücke. Sie sind einer von mehreren Faktoren, die Apple abwägt, nicht der ausschlaggebende – und ein hoher Verbrauchswert ist kein Schalter für eine Ablehnung. Betrachten Sie sie als Kontext, den Sie beisteuern, nicht als Fall, den Sie verhandeln.
Was sollten Entwickler tun, wenn sie einen CONSUMPTION_REQUEST erhalten?
Die Benachrichtigung validieren, Transaktion und Kunde identifizieren, die Einwilligung bestätigen, korrekte Verbrauchsdaten zusammenstellen, diese innerhalb von Apples Zeitfenster senden und anschließend festhalten, was passiert ist.
Zehn Schritte in der Praxis:
1. Empfangen Sie die Benachrichtigung an Ihrem konfigurierten Server-Endpunkt und speichern Sie sie sofort.
2. Prüfen Sie die signierte Payload, bevor Sie ein Feld als echt behandeln.
3. Lesen Sie den Benachrichtigungstyp aus und routen Sie ihn. Ein Consumption Request ist kein Erstattungsergebnis.
4. Identifizieren Sie die zugehörige Transaktion aus der dekodierten Payload.
5. Ordnen Sie die Transaktion einem Kundenkonto in Ihrem eigenen System zu.
6. Prüfen Sie, ob die Einwilligung dieses Kunden eine Antwort zulässt.
7. Ziehen Sie Liefer- und Nutzungsdaten aus Ihren Aufzeichnungen, nicht aus Schätzungen.
8. Bereiten Sie die Antwort vor und prüfen Sie sie gegen die Validierungsregeln der Felder.
9. Senden Sie sie an Apples Consumption-Endpunkt und erfassen Sie das Ergebnis.
10. Verfolgen Sie das anschließende Erstattungsergebnis und aktualisieren Sie dann Entitlement und Datensätze.
Wie sollten Entwickler einen CONSUMPTION_REQUEST validieren?
Prüfen Sie die Signatur, bevor Sie dem Inhalt vertrauen. Benachrichtigungen kommen als signierte JWS-Payloads an, dokumentiert in der Apple-Dokumentation zu App Store Server Notifications, und Ihr Handler sollte sie gegen Apples Zertifikatskette prüfen und bestätigen, dass die Bundle-ID zu Ihrer App passt.
Der Grund ist einfach. Ihre Notification-URL ist ein öffentlicher Endpunkt. Eine Implementierung, die alles parst, was eintrifft, und darauf reagiert, kann von jedem gesteuert werden, der die URL findet.
Drei Details des Handlers sind genauso wichtig wie die Signatur:
Antworten Sie mit dem richtigen Statuscode. Apple wertet HTTP 200 bis 206 als Erfolg. Ein 40x oder 50x weist den App Store an, es erneut zu versuchen. Melden Sie Erfolg, sobald Sie die Benachrichtigung gespeichert haben – nicht erst, wenn die Verarbeitung abgeschlossen ist. Das sind zwei verschiedene Zeitpunkte, und wer sie koppelt, riskiert, dass ein langsamer nachgelagerter Job unnötige Wiederholungen auslöst.
Behandeln Sie Duplikate. Wiederholungen bedeuten, dass dieselbe Benachrichtigung mehrfach eintreffen kann; jede enthält eine Notification-UUID, mit der Sie deduplizieren können. Bestätigen Sie Wiederholungen, statt mit einem Fehler zu antworten – eine Fehlerantwort startet den Retry-Zyklus nur neu.
Denken Sie daran, dass sich die Sandbox anders verhält. Wiederholungen gelten in der Produktion. In der Sandbox versucht der App Store die Zustellung nur einmal. Ein Handler, der im Test unauffällig wirkt, kann in der Produktion trotzdem Events verlieren – und umgekehrt.
Was sollten Entwickler vor der Antwort prüfen?
Vier Dinge, in dieser Reihenfolge.
Zuerst die Einwilligung, denn sie kann alles stoppen. Apple verlangt eine gültige Einwilligung des Kunden, bevor Sie dessen Daten weitergeben; sie einzuholen ist Ihre Aufgabe, nicht die von Apple, und die Benachrichtigung selbst enthält kein Einwilligungs-Flag. Apple stellt außerdem klar, dass der App-Tracking-Transparency-Dialog hierfür nicht der richtige Mechanismus ist. Liegt keine Einwilligung vor, lautet die Vorgabe: nicht antworten.
Zweitens die Identität der Transaktion. Sie müssen wissen, um welchen Kauf es sich handelt und welcher Account dahintersteht. Genau um diese Zuordnung geht es bei appAccountToken und Apples Erstattungsabwehr – ohne stabile Verknüpfung von Transaktion und Account raten Sie unter Zeitdruck.
Drittens der Produkttyp, denn er bestimmt, welche Optionen Ihnen zur Verfügung stehen. Und schließlich, ob Sie überhaupt verwertbare Daten haben. Wenn Ihre Systeme nicht sagen können, ob der Inhalt geliefert wurde, sollten Sie das wissen, bevor Sie eine Antwort zusammenstellen.
Welche Verbrauchsinformationen können Entwickler an Apple senden?
Apples aktuelle Dokumentation zu Send Consumption Information definiert fünf Felder. Drei sind Pflicht, zwei optional.
Feld | Pflicht | Im Klartext |
customerConsented | Ja | Hat der Kunde zugestimmt? Muss true sein, sonst wird die Anfrage abgelehnt. |
deliveryStatus | Ja | Hat Ihre App den Kauf tatsächlich funktionsfähig geliefert – und wenn nicht, warum nicht? |
sampleContentProvided | Ja | Konnte der Kunde es vor dem Kauf ausprobieren? |
consumptionPercentage | Nein | Wie viel wurde genutzt? In Milli-Einheiten – die Hälfte ist 50000, nicht 50. |
refundPreference | Nein | Was Sie bevorzugen: vollständig erstatten, ablehnen oder anteilig erstatten. |
Zwei Regeln sorgen immer wieder für Fehler. Ist der Lieferstatus etwas anderes als „geliefert“, muss der Verbrauchsprozentsatz null sein. Und die Erstattungspräferenz ist eine Präferenz, keine Anweisung; Apple kann anders entscheiden und tut das auch.
Prüfen Sie, welchen Endpunkt Sie verwenden. Apple dokumentiert außerdem Apples ConsumptionRequestV1-Dokumentation, die frühere Version mit einem Body aus zwölf Feldern, die die meisten Drittanbieter-Artikel noch beschreiben. Apples Hinweis dort verweist Standard-In-App-Käufe auf den aktuellen Endpunkt und beschränkt V1 auf Käufe über die Advanced Commerce API. Wenn Ihre Integration älter ist als diese Änderung, sollten Sie das zuerst prüfen.
Wie viel Zeit haben Entwickler für die Antwort auf einen CONSUMPTION_REQUEST?
Apples aktuelle Dokumentation erwartet eine Antwort innerhalb von 12 Stunden nach der Benachrichtigung.
Hier lohnt sich ein genauer Blick. Apple wiederholt fehlgeschlagene Zustellungen fünfmal – jeweils 1, 12, 24, 48 und 72 Stunden nach dem vorherigen Versuch. Legt man das neben ein 12-Stunden-Fenster, wird die Rechnung unangenehm: Verpasst Ihr Endpunkt die erste Zustellung, kommt der erste Wiederholungsversuch eine Stunde später, und alles ist in Ordnung. Verpasst er auch diesen, landet der nächste Versuch nach rund dreizehn Stunden – wenn das Fenster bereits geschlossen ist.
Die Zuverlässigkeit des Endpunkts ist hier also keine allgemeine Hygienefrage. Speziell bei Consumption Requests ist rund eine Stunde Ausfall verkraftbar, ein halber Tag nicht.
Apple sagt nicht, dass ein verpasstes Fenster automatisch zur Genehmigung der Erstattung führt, und es wäre falsch, das zu behaupten. Es bedeutet lediglich, dass Apple ohne Informationen entscheidet, die Sie hätten liefern können.
Was passiert, nachdem der Entwickler geantwortet hat?
Apple nimmt Ihre Informationen in die Prüfung auf, wägt sie mit allem anderen ab und entscheidet. Das Ergebnis kommt als separate Benachrichtigung: genehmigt, abgelehnt oder widerrufen, falls Apple eine bereits genehmigte Erstattung später rückgängig macht.
Hier passieren drei verschiedene Dinge, die man auseinanderhalten sollte. Ihre Antwort ist Information. Apples Entscheidung ist eine Entscheidung. Ihr System-Update ist eine Zustandsänderung. Nur das mittlere liegt bei Apple, und das dritte passiert nur, wenn Sie es bauen.
So verarbeiten Entwickler Apple-Erstattungen nach der Antwort
Sobald das Ergebnis eintrifft, liegt die Arbeit wieder bei Ihnen.
Halten Sie das Ergebnis zur Transaktion und zum Kunden fest. Aktualisieren Sie den Abo-Status, denn ein erstatteter Zeitraum beendet das Abo in der Regel, statt es weiterlaufen zu lassen. Entziehen Sie das Entitlement bei einer genehmigten Erstattung, stellen Sie es bei einem Widerruf wieder her und behandeln Sie den anteiligen Fall, bei dem nur ein Teil einer Transaktion zurückgenommen wird.
Ordnen Sie den Betrag anschließend der richtigen Berichtsperiode zu und bewahren Sie die Erstattung in einer abfragbaren Historie auf. Diese Historie zeigt Ihnen später, ob ein bestimmtes Produkt oder ein Preispunkt einen überproportionalen Anteil verursacht – und sie ist das, was der Support braucht, wenn ein Kunde fragt, was mit seinem Zugang passiert ist.
Welche Fehler passieren bei der Verarbeitung von CONSUMPTION_REQUEST am häufigsten?
Die, die immer wieder auftauchen:
• Die Benachrichtigung als Erstattung behandeln und den Zugang sofort entziehen. Es ist noch nichts entschieden.
• Die Signaturprüfung überspringen, weil die Payload im Test unauffällig aussieht.
• Erst dann feststellen, dass es keinen Einwilligungs-Flow gibt, wenn eine Antwort fällig ist.
• Geschätzte statt echter Verbrauchswerte senden.
• Die Anfrage abschicken und nie prüfen, ob sie erfolgreich war. Eine fehlgeschlagene Übermittlung sieht im Nachhinein genauso aus wie eine erfolgreiche.
• Eine Kündigung mit einer Erstattung verwechseln. Es sind unterschiedliche Ereignisse mit unterschiedlichen Auswirkungen auf den Zugang.
• Die Ergebnisse „genehmigt“ und „abgelehnt“ behandeln, aber den Widerrufsfall vergessen – was zahlende Kunden aussperrt.
• Sich darauf verlassen, dass jemand eine Benachrichtigung manuell bemerkt – bei einer 12-Stunden-Frist.
Lässt sich die Verarbeitung von CONSUMPTION_REQUEST automatisieren?
Ja, und fast vollständig sollte sie das auch, denn nahezu jeder Schritt ist deterministisch.
Automatisieren lassen sich Überwachung und Validierung der Benachrichtigungen, Transaktionssuche, Einwilligungsprüfung, Aufbereitung der Verbrauchsdaten, Übermittlung, Protokollierung der Antwort, Ergebnisverfolgung, interne Alerts und Reporting. Nichts davon erfordert Urteilsvermögen im Moment selbst.
Menschlich bleibt, was vorgelagert ist: den Einwilligungs-Flow in Ihrer App zu gestalten und festzulegen, wie Ihre Erstattungspräferenz aussehen soll. Und Automatisierung hat keinen Einfluss auf Apples Entscheidung – egal, was manche Tools suggerieren.
Wie RefundSensor Entwickler bei Apple-Erstattungs-Workflows unterstützt
Erstattungsmanagement im App Store ist die Kategorie, und RefundSensor deckt die Entwicklerseite davon ab: Überwachung von Apple-Erstattungs-Workflows, Abwicklung des unterstützten Antwortpfads für Consumption Requests, Verfolgung von Erstattungsereignissen und -ergebnissen sowie Abnahme der repetitiven Arbeit.
In der Praxis gehen Antworten innerhalb des Zeitfensters raus, ohne dass jemand um 3 Uhr nachts auf ein Dashboard schaut, und Erstattungsdatensätze bleiben auch bei wachsendem Volumen korrekt. Es verhindert keine Erstattungen und kann Apples Entscheidung nicht beeinflussen. Es beseitigt die manuelle Überwachung und die übersehenen Schritte.
Wo diese Regeln dokumentiert sind
Send Consumption Information – der aktuelle Endpunkt. Einwilligungspflicht, das 12-Stunden-Fenster und die fünf Anfragefelder. Für Standard-In-App-Käufe bauen Sie gegen diesen Endpunkt.
Send Consumption Information V1 – der frühere Endpunkt mit dem Body aus zwölf Feldern. Hilfreich, um festzustellen, welche Version Ihre Integration aufruft, sowie für Käufe über die Advanced Commerce API.
App Store Server Notifications – Zustellung der Benachrichtigungen, das signierte Payload-Format, die erwarteten Antwortcodes und der Retry-Zeitplan.
Falls das noch manuell läuft
Ein 12-Stunden-Fenster, ein Retry-Zeitplan, der es überdauern kann, und Benachrichtigungen, die über Nacht eintreffen, passen schlecht zu manueller Überwachung. RefundSensor übernimmt die Entwicklerseite dieser Workflows – Validierung der Benachrichtigungen, Vorbereitung und Übermittlung der Antworten innerhalb des Zeitfensters und Verfolgung der Ergebnisse bis in Ihre Entitlement-Datensätze.
Häufig gestellte Fragen
Eine App Store Server Notification, die Ihrem Server mitteilt, dass ein Kunde eine Erstattung beantragt hat und Apple Sie einlädt, Verbrauchsinformationen zu diesem Kauf zu senden. Sie ist weder eine Erstattungsbenachrichtigung noch eine Entscheidung. Apple entscheidet separat und behandelt Ihre Antwort als einen von mehreren Faktoren.
Weil Apple nicht sehen kann, was in Ihrer App passiert ist. Apple kennt die Transaktion und die Account-Historie, aber nicht, ob der Inhalt geliefert wurde, ob er funktioniert hat oder wie viel der Kunde genutzt hat. Dieser Kontext liegt in Ihren Systemen, deshalb fragt Apple ihn während der Prüfung ab.
Die signierte Benachrichtigung prüfen, die Transaktion und den dahinterstehenden Kunden identifizieren, das Vorliegen der Einwilligung bestätigen, echte Liefer- und Nutzungsdaten aus Ihren Aufzeichnungen zusammenstellen und dann innerhalb des Zeitfensters an Apples Consumption-Endpunkt senden. Erfassen Sie das Ergebnis der Antwort, statt anzunehmen, dass der Aufruf erfolgreich war.
Fünf Felder am aktuellen Endpunkt. Drei Pflichtfelder: Einwilligung des Kunden, Lieferstatus und ob Beispielinhalte bereitgestellt wurden. Zwei optionale: Verbrauchsprozentsatz und Ihre Erstattungspräferenz. Der frühere V1-Endpunkt verlangte zwölf Felder, weshalb ältere Anleitungen eine längere Liste beschreiben.
Apples aktuelle Dokumentation beschreibt die Benachrichtigung im Zusammenhang mit Erstattungsanfragen über alle Produkttypen hinweg – breiter, als ältere Dokumente nahelegten. Apple gibt keine Garantie für jeden Fall, bauen Sie also einen Handler, der reagiert, wenn eine Anfrage eintrifft, statt Logik, die davon ausgeht, dass immer eine kommt.
Apple erwartet eine Antwort innerhalb von 12 Stunden nach der Benachrichtigung. Beachten Sie, dass Apples Retry-Zeitplan für fehlgeschlagene Zustellungen bei 1, 12, 24, 48 und 72 Stunden liegt. Ein Endpunkt, der über den ersten Wiederholungsversuch hinaus ausfällt, erhält die Benachrichtigung womöglich erst, wenn das Fenster bereits geschlossen ist.
Apple wägt sie zusammen mit anderen Faktoren ab und entscheidet. Das Ergebnis kommt als separate Benachrichtigung, die anzeigt, ob die Erstattung genehmigt, abgelehnt oder später widerrufen wurde. Danach ist es Ihre Aufgabe, Entitlement, Abo-Status und Umsatzdatensätze an den neuen Transaktionsstatus anzupassen.
Ja. Validierung, Transaktionssuche, Einwilligungsprüfung, Datenaufbereitung, Übermittlung, Protokollierung und Ergebnisverfolgung sind alle deterministisch. Menschlich bleibt die Gestaltung des Einwilligungs-Flows und die Festlegung Ihrer Erstattungspräferenz. Automatisierung hat keinen Einfluss auf Apples Erstattungsentscheidung.
