Apple's Send Consumption Information vraagt nu om vijf velden, niet twaalf, en hier is elk daarvan

De lijst met feiten waar Apple u om vraagt wanneer een klant een terugbetaling wil, is een stuk korter geworden. De Send Consumption Information-payload, het ene antwoord dat een ontwikkelaar in een App Store-terugbetalingsbeslissing mag inbrengen, had vroeger twaalf velden. Nu heeft die er vijf. Apple heeft die rond WWDC24 ingekort en de meeste oude vragen over accountprofilering samengevouwen tot twee eenvoudige vragen en een getal. Minder velden is geen kleine wijziging. Het verandert welk bewijs Apple weegt, en het verandert welke velden u zich niet kunt veroorloven verkeerd in te vullen.

Hier is waarom dit uw aandacht verdient en niet slechts een schemanotitie is. Deze payload is het enige moment in een Apple-terugbetaling waarop uw kant van het verhaal de beslissing bereikt. Een terugbetaling voor een verbruiksaankoop draait omzet terug die u al echt geld hebt uitgegeven om te leveren, en de vijf velden zijn hoe u Apple vertelt dat het product is geleverd en gebruikt. Mist u het venster van 12 uur of vult u een veld verkeerd in, dan beslist Apple op basis van de klacht van de klant alleen.

Wat Send Consumption Information is

Send Consumption Information is het App Store Server API-eindpunt dat u aanroept nadat Apple uw server een CONSUMPTION_REQUEST-melding heeft gestuurd. Die melding betekent dat een klant Apple om een terugbetaling voor een in-app-aankoop heeft gevraagd en dat Apple uw inbreng wil voordat het beslist. U antwoordt door een kleine JSON-body, de ConsumptionRequest, met een PUT naar het eindpunt te sturen. Apple leest die, weegt die tegen de geschiedenis van de klant, en neemt de beslissing. U beslist nooit over de terugbetaling. U levert feiten.

De body is de hele interface. Er is geen apart formulier, geen bezwaar, en geen tweede inzending die telt. Wat u ook in die ene payload verstuurt, is uw volledige zaak, dus de betekenis van elk veld weegt zwaarder dan het aantal velden doet vermoeden.

De vijf velden waar Apple nu om vraagt

De huidige ConsumptionRequest heeft vijf leden. Drie zijn verplicht en twee zijn optioneel. Alles wat Apple vroeger over het account van de klant vroeg, zijn accountduur, zijn totale uitgaven, zijn totale terugbetalingen, zijn speeltijd, is verwijderd uit wat u verstuurt.

customerConsented is de poort

customerConsented is een Boolean, en het is het veld dat bepaalt of u überhaupt iets verstuurt. Het legt vast of de klant ermee akkoord ging dat u verbruiksgegevens met Apple deelt. Apple's richtlijn is duidelijk: als de klant niet toestemde, verstuur de verbruiksinformatie dan niet. Dit is dus geen veld dat u op true zet om uw zaak te versterken. Het weerspiegelt een echte ja of nee die u al moet bezitten, en een false hier betekent dat de rest van de payload niet verstuurd mag worden.

deliveryStatus is het veld dat terugbetalingen beweegt

deliveryStatus is een String-enum, en het is de sterkste hefboom die u hebt. Het vertelt Apple of uw app daadwerkelijk een werkende in-app-aankoop heeft geleverd. Eén waarde zegt ja. De andere vier zeggen nee, elk om een andere reden, en elk vertelt Apple dat de klant een gegronde klacht heeft.

sampleContentProvided beantwoordt een eerlijkheidsvraag

sampleContentProvided is een Boolean. Het legt vast of u de klant een gratis proef, een proefversie, of duidelijke informatie hebt gegeven over wat de aankoop doet voordat hij kocht. Een true hier is een klein eerlijkheidssignaal: de klant had de kans om te weten wat hij kocht. Het beslist niets op zichzelf, maar het is een van slechts drie verplichte velden, dus Apple wil het duidelijk in elk antwoord hebben.

consumptionPercentage is nu een getal, geen status

Dit is het veld dat het meest is veranderd. De oude payload had consumptionStatus, een viertraps enum: UNDECLARED, NOT_CONSUMED, PARTIALLY_CONSUMED, FULLY_CONSUMED. De nieuwe payload vervangt die door consumptionPercentage, een geheel getal gemeten in milliunits. 100,000 milliunits betekent dat het item volledig is verbruikt, dus 50,000 is de helft en 0 is onaangeroerd. Een nauwkeurig getal verslaat een indeling in vier bakken, want het laat u zeggen dat een klant 90 procent van een tegoedpakket heeft opgebruikt in plaats van naar beneden af te ronden tot gedeeltelijk verbruikt.

Eén kanttekening waar mensen over struikelen. Voor automatisch verlengende abonnementen berekent Apple het verbruik zelf op basis van de verstreken tijd, dus consumptionPercentage is bedoeld voor verbruiksaankopen en niet-verlengende aankopen. Verstuur het waar het van toepassing is, en laat Apple het afleiden waar dat niet zo is.

refundPreference geeft een voorkeur aan, geen oordeel

refundPreference is een optionele tekenreeks, en hier vertelt u Apple welk resultaat u zou verkiezen. Ook dit veld veranderde van vorm. Het oude veld was een getal met waarden zoals prefer-grant, prefer-decline en no-preference. Het nieuwe is een benoemde tekenreeks met drie waarden.

Wat Apple heeft laten vallen, en waarom het ertoe doet

De oude ConsumptionRequest had twaalf velden. Zeven daarvan zijn verdwenen uit wat u verstuurt. accountTenure, lifetimeDollarsPurchased, lifetimeDollarsRefunded, playTime, userStatus, platform en appAccountToken waren de accountprofilerende helft van de payload, de velden die u vroegen een klant in te delen naar hoe lang hij een account had, hoeveel hij had uitgegeven, hoeveel hem was terugbetaald, en hoe lang hij de app had gebruikt.

Apple heeft ze om een vermeldenswaardige reden geschrapt. Die velden vroegen ontwikkelaars om een profiel van de klant af te geven, en de meeste ontwikkelaars lieten ze ofwel ongedeclareerd of gokten. De vijf die overblijven gaan over de aankoop en de levering, feiten die u daadwerkelijk kunt verifiëren vanuit uw eigen systemen. De verschuiving gaat van wie de klant is naar wat er met deze specifieke aankoop gebeurde.

Het eindpunt en de klok

U verstuurt de payload met een HTTP PUT naar het Send Consumption Information-eindpunt, gekoppeld aan de transactie-id van de betwiste aankoop: PUT /inApps/v1/transactions/consumption/{transactionId}. Een succes geeft 202 Accepted terug, en de response-body is leeg. Dat lege antwoord is te verwachten, geen bug. Het bevestigt dat Apple uw gegevens in de wachtrij heeft gezet, en het vertelt u niets over de uiteindelijke uitkomst, die later arriveert als een REFUND- of REFUND_DECLINED-melding.

De klok is het deel dat u niet kunt oprekken. Apple geeft u 12 uur vanaf de CONSUMPTION_REQUEST om te reageren. Alleen uw eerste antwoord wordt gebruikt, dus de eerste payload moet de volledige en juiste zijn. Apple kan de CONSUMPTION_REQUEST meer dan eens versturen voor dezelfde aankoop, maar de deadline op elk is vast, en een handmatige beoordeling past over tijdzones en weekenden heen zelden binnen 12 uur.

Wat een verkeerd behandeld veld u kost

Het geld verliet het gebouw voordat de terugbetaling dat deed

Een terugbetaling voor een verbruiksaankoop is geen schone terugdraaiing. Tegen de tijd dat een klant zijn geld terugvraagt voor een pakket tegoeden of een reeks AI-generaties, hebt u al uitgegeven om het te leveren: GPU-inferentie bij elk verzoek, model-API-aanroepen van derden die per token worden gefactureerd, opslag voor wat u ook produceerde, en elke maker- of partneruitbetaling die aan dat gebruik is gekoppeld. De winkelprijs gaat terug naar de klant. Uw leveringskosten komen niet naar u terug. Dus een terugbetaling die u had kunnen aanvechten is geen break-evengebeurtenis, het is een nettoverlies van alles wat u betaalde om het account te bedienen.

De vijf velden zijn hoe u voorkomt dat u twee keer betaalt

deliveryStatus ingesteld op DELIVERED en een hoge consumptionPercentage zijn de twee feiten die Apple vertellen dat de klant het product heeft ontvangen en gebruikt. Ze zijn uw bewijs dat de rekenkracht, de API-aanroepen en de opslag allemaal hun werk hebben gedaan. Laat de payload onverstuurd en Apple hoort dat nooit. Het beslist op basis van de klacht van de klant, de terugbetaling gaat waarschijnlijker door, en u draait op voor zowel de teruggedraaide omzet als de leveringskosten daarachter.

Chargebacks zijn de ergere deur, en stilte wijst ernaar

Een klant die via Apple's terugbetalingsstroom geen voldoening krijgt, kan de afschrijving nog steeds betwisten bij zijn bank. Een chargeback op een kaart is definitief, brengt een vaste geschilkosten met zich mee, en haalt de beslissing uit Apple's handen en die van u. De CONSUMPTION_REQUEST goed beantwoorden houdt het geschil binnen Apple's systeem, waar u een stem hebt. Het negeren duwt grensgevallen richting het ene kanaal waar u er geen hebt.

Hoe RefundHalt het afhandelt

De vijf velden lijken eenvoudig totdat u ze correct moet invullen, binnen 12 uur, bij elke CONSUMPTION_REQUEST, gekoppeld aan de juiste transactie. RefundHalt vangt de melding op, leest uw eigen leverings- en gebruiksgegevens voor die aankoop, en verstuurt de payload automatisch voordat het venster sluit. deliveryStatus weerspiegelt wat uw logs daadwerkelijk tonen, consumptionPercentage komt uit werkelijk gebruik in plaats van een gok, en refundPreference volgt het beleid dat u eenmaal hebt ingesteld. U krijgt de betwistbare terugbetaling met bewijs beoordeeld, niet een gemiste deadline en een beslissing genomen zonder u.