Hänge an jeden App-Store-Kauf einen appAccountToken, sonst kannst du die Rückerstattung nicht abwehren

Ein Kunde verlangt von Apple eine Rückerstattung, Apple schickt deinem Server einen CONSUMPTION_REQUEST, und du hast zwölf Stunden, um mit echten Daten darüber zu antworten, wie diese Person das Produkt genutzt hat. Dann öffnest du die Benachrichtigung und merkst, dass du keine Ahnung hast, wer das ist. Die Transaktion trägt eine originalTransactionId und eine Produkt-ID, aber nichts, das auf das Konto in deiner eigenen Datenbank zeigt. Genau diese Lücke schließt appAccountToken, und wenn du ihn zum Kaufzeitpunkt nicht gesetzt hast, kannst du sie für diesen Verkauf im Nachhinein nicht mehr schließen.

appAccountToken ist eine UUID, die du an einen Kauf hängst, damit die entstehende App-Store-Transaktion einen Verweis auf genau den Nutzer in deinem System trägt. Setze ihn, und jede Rückerstattungsfrage, die Apple je zu diesem Kunden stellt, kommt mit dessen Identität an. Lass ihn weg, und du rätst. Hier steht, was das Feld ist, wie du es setzt, welcher neue Endpunkt Käufe außerhalb deiner App rettet und was die fehlende Verknüpfung wirklich kostet, wenn eine Rückerstattung eintrifft.

Was appAccountToken wirklich ist

appAccountToken ist eine undurchsichtige UUID, die du erzeugst und im Moment des Kaufs an StoreKit übergibst. Apple speichert sie auf der Transaktion und gibt sie in den Transaktionsinformationen für diesen Kauf zurück, und sie bleibt dort. In Apples Worten ist es "die UUID, die die Transaktion mit dem Konto des Nutzers in deinem eigenen Dienst verknüpft." Die einzige Formatregel ist, dass es eine UUID sein muss. Apple liest sie nicht, prüft nicht, worauf sie verweist, und interessiert sich nicht dafür, was sie auf deiner Seite bedeutet. Es ist eine Verknüpfung, die du kontrollierst.

Weil sie auf der Transaktion liegt, kommt sie überall dort zurück, wo die Transaktion zurückkommt. Die signierte Transaktion in einer Server-Benachrichtigung, die Antwort von Get Transaction Info der App Store Server API und jede Verlängerung in einer Abo-Kette tragen alle denselben Token, wenn du ihn beim ursprünglichen Kauf gesetzt hast. Eine UUID, einmal angehängt, folgt der Abrechnung des Kunden über die gesamte Dauer der Beziehung.

Es muss eine echte UUID sein, sonst verschwindet sie stillschweigend

Die eine Regel, die Apple durchsetzt, ist das Format. StoreKit 2 verlangt eine RFC 4122 UUID. Übergibst du eine zusammengesetzte Zeichenkette, eine Ganzzahl-ID oder eine E-Mail-Adresse, wirft StoreKit keinen Fehler. Es verwirft den Wert und die Transaktion kommt mit appAccountToken auf nil gesetzt zurück. Entwickler stolpern ständig darüber, und das Symptom ist immer dasselbe, irgendeine Variante von "appAccountToken is missing in the transaction payload" in Apples eigenen Foren, fast immer, weil der übergebene Wert keine gültige UUID war. Erzeuge serverseitig eine echte UUID, speichere sie zum Konto und übergib StoreKit niemals etwas anderes.

Wie du ihn zum Kaufzeitpunkt setzt

In StoreKit 2 ist es eine einzige Kaufoption. Erzeuge die UUID auf deinem Server, wenn der Nutzer sich anmeldet oder zum ersten Mal zur Kasse gelangt, speichere sie im Kontodatensatz und übergib denselben Wert an den Kaufaufruf.

Die Signatur lautet Product.PurchaseOption.appAccountToken(_ token: UUID), und ein Kauf sieht aus wie try await product.purchase(options: [.appAccountToken(token)]). Wenn die Transaktion zurückkommt, über die App Store Server API verifiziert oder per Server-Benachrichtigung geliefert, trägt sie diese UUID, und dein Server findet den Kunden mit einer einzigen Abfrage.

Verwende einen stabilen Token pro Konto

Erzeuge nicht für jeden Kauf desselben Nutzers einen frischen Token. Apple gibt den Token bei Verlängerungen, Abbuchungsversuchen und Upgrades in derselben Kette zurück, sodass eine stabile UUID pro Konto dir einen sauberen Faden vom ersten Kauf durch jedes künftige Ereignis gibt. Ein Token, der sich pro Kauf ändert, reißt diesen Faden und untergräbt den ganzen Zweck. Ein Konto, ein Token, jedes Mal wiederverwendet, wenn dieses Konto kauft.

Der Endpunkt, der Käufe außerhalb der App rettet

Bis 2025 gab es ein Loch. Wenn ein Kunde einen Angebotscode einlöste oder einen beworbenen In-App-Kauf direkt aus dem App Store tätigte, lief in deiner App nie der Kaufablauf, also gab es nirgends, wo appAccountToken zu setzen war. Diese Transaktionen kamen anonym an und blieben es.

WWDC 2025 schloss die Lücke mit dem Endpunkt Set App Account Token. Dein Server ruft PUT /inApps/v1/transactions/{originalTransactionId}/appAccountToken auf der App Store Server API mit der UUID im Body auf, und Apple setzt den Token auf dieser Transaktion. Es funktioniert für jeden Produkttyp, deckt Einlösungen von Angebotscodes und beworbene Käufe ab, und der Wert, den du sendest, überschreibt jeden bereits auf der Transaktion vorhandenen Token. Du kannst einen Kauf jetzt im Nachhinein von deinem Server aus zuordnen, ohne dass er je durch deine App läuft.

Wo dich die fehlende Verknüpfung Geld kostet

Der Sinn des Tokens sind nicht ordentliche Aufzeichnungen. Er ist, dass Apples eine Rückerstattungsfrage an Entwickler, der CONSUMPTION_REQUEST, nur beantwortbar ist, wenn du den Kunden findest, um den es geht.

Wenn ein Käufer eine Rückerstattung für ein Verbrauchsprodukt oder ein nicht erneuerbares Abo verlangt, schickt Apple deinem Server eine CONSUMPTION_REQUEST-Benachrichtigung und gibt dir zwölf Stunden, um mit Send Consumption Information zu antworten. Deine Antwort sind Daten über genau diesen Kunden: wie viel des Produkts er verbraucht hat, wie lange sein Konto besteht, wie hoch seine Gesamtausgaben sind, wie sein Lieferstatus ist. appAccountToken ist selbst eines der Felder in dieser Anfrage, und wichtiger noch, es ist die Art und Weise, wie die Transaktion der Benachrichtigung dem Konto zugeordnet wird, dessen Nutzung du gleich beschreiben wirst. Kein Token, keine Zuordnung, keine korrekte Antwort.

Was eine leere Antwort wirklich kostet

Eine nicht identifizierte Rückerstattung erzwingt eine schlechte Wahl. Du kannst die Verbrauchsanfrage mit nichts beantworten, was als geringer Verbrauch gelesen wird und Apple in Richtung Gewährung der Rückerstattung drängt, auch bei Kunden, die das Produkt intensiv genutzt haben. Oder du rätst. So oder so erstattest du Käufe, für die du die Beweise zur Abwehr hattest, und du hast die echten Kosten ihrer Bereitstellung bereits bezahlt.

Diese Kosten sind nicht der Verkaufspreis. Ein Verbrauchsprodukt, das eine Reihe von Modell-API-Aufrufen ausführte, Bilder generierte, ein Video exportierte oder eine Creator-Auszahlung auslöste, gab echtes Geld aus, sobald es geliefert wurde. Die Rückerstattung gibt die Zahlung des Kunden zurück. Sie gibt nicht die Rechnung des Anbieters zurück. Multipliziere einen nicht identifizierbaren Kunden mit jeder Rückerstattung, die er einreicht, und mit jedem Serien-Rückerstatter, der darauf zählt, dass du nicht weißt, wer er ist, und der Token, den du weggelassen hast, wird zur teuersten Codezeile, die du nie geschrieben hast.

Dieselbe Idee gibt es unter Android, unter anderem Namen

Google Play löst das identische Problem mit setObfuscatedAccountId, das eine Kontokennung an einen Kauf hängt, damit Googles Rückbuchungsprüfung über orders.reviewrefund gegen einen echten Nutzer beantwortet werden kann. Anderer Store, andere Mechanik, dieselbe Lektion: Hänge die Identität zum Kaufzeitpunkt an, sonst kannst du den Streitfall später nicht abwehren. Im App Store ist dieses Werkzeug appAccountToken, und es muss eine UUID sein.

Drei Gewohnheiten, die den Token an Ort und Stelle halten

• Erzeuge eine UUID pro Konto und speichere sie. Ein stabiler Token pro Kunde, erstellt bei der Anmeldung oder beim ersten Bezahlvorgang, im Datensatz gespeichert und für jeden Kauf wiederverwendet.
• Validiere, bevor du ihn übergibst. Bestätige in deinem Kaufcode, dass der Wert eine echte UUID ist, damit eine fehlerhafte ID niemals stillschweigend zu einem nil-Token auf der Transaktion werden kann.
• Fülle Käufe außerhalb der App nach. Wenn eine Server-Benachrichtigung für eine Einlösung eines Angebotscodes oder einen beworbenen Kauf ohne Token eintrifft, rufe den Endpunkt Set App Account Token auf, um den richtigen anzuhängen.

Tu diese drei Dinge, und jede Transaktion, die Apple dir je schickt, Rückerstattungsanfragen inbegriffen, kommt bereits mit dem Kunden verknüpft an, zu dem sie gehört.

Das ist die Grundlage, auf die sich RefundHalt stützt. Wir lesen appAccountToken von jeder Transaktion und Server-Benachrichtigung ab, verknüpfen ihn mit der Nutzung, die wir für dieses Konto ohnehin verfolgen, und beantworten Apples Verbrauchsanfrage innerhalb des Zwölf-Stunden-Fensters mit den echten Zahlen des Kunden. Der Token ist der Faden. Setze ihn einmal, und deine Rückerstattungsabwehr hat etwas, woran sie sich festhalten kann.