Ogni richiesta di rimborso Apple ora arriva con un motivo, e consumptionRequestReason è come lo leggi

Apple ha cambiato il modo in cui le richieste di rimborso arrivano sul tuo server, e molti sviluppatori non se ne sono mai accorti. Dall'aggiornamento 2.11 di App Store Server Notifications annunciato alla WWDC24, ogni notifica CONSUMPTION_REQUEST porta con sé un campo chiamato consumptionRequestReason. È il motivo dichiarato dal cliente stesso per chiedere indietro i propri soldi. Una semplice stringa, cinque valori possibili, consegnata dentro lo stesso payload a cui hai già dodici ore per rispondere.

Il motivo della richiesta di rimborso Apple non decide nulla da solo. Ciò che fa è dirti in quale di cinque situazioni molto diverse ti trovi, così da smettere di inviare gli stessi dati di consumo generici a un rimborso che dovresti concedere e a un rimborso che dovresti contestare. Ecco cos'è questo campo, i valori esatti che Apple può inviare, cosa segnala ciascuno e come dovrebbe cambiare la preferenza e le prove che rimandi indietro.

Cos'è davvero consumptionRequestReason

consumptionRequestReason è un campo di tipo stringa nell'oggetto data di una notifica CONSUMPTION_REQUEST. Apple lo ha aggiunto nella versione 2.11 di App Store Server Notifications, insieme alle modifiche della WWDC24 al flusso di rimborso. Prima di allora, la richiesta arrivava con la transazione firmata e nulla sul motivo. Rispondevi alla cieca. Ora il motivo dichiarato dal cliente viaggia con la richiesta.

Leggi con attenzione la parola dichiarato. Questo è il motivo che il cliente ha selezionato quando ha presentato la richiesta ad Apple, non un fatto che Apple ha verificato. UNINTENDED_PURCHASE non dimostra che l'acquisto sia rimasto inutilizzato, e UNSATISFIED_WITH_PURCHASE non dimostra che il prodotto fosse difettoso. Il valore è una lente, non un verdetto. Lo abbini comunque ai tuoi registri di consegna e di utilizzo.

Viaggia nella notifica che gestisci già

CONSUMPTION_REQUEST è l'unico flusso di Apple che chiede prove allo sviluppatore. Il suo equivalente su Google Play è la revisione del chargeback tramite orders.reviewrefund. Quando ne arriva una, hai 12 hours per rispondere chiamando Send Consumption Information, un PUT verso l'endpoint di consumo delle transazioni. consumptionRequestReason ora fa parte di quella stessa notifica, quindi non c'è nulla di nuovo a cui iscriversi. Se già analizzi CONSUMPTION_REQUEST, il motivo è un campo che probabilmente stavi ignorando.

I cinque motivi, e cosa ti dice ciascuno

Apple documenta esattamente cinque valori. Ne arriva uno per richiesta. Ecco l'insieme completo e come leggere ognuno nella pratica.

UNINTENDED_PURCHASE è la categoria del tocco accidentale

Questo è il motivo che un genitore seleziona dopo che un bambino ha comprato 10,000 monete, o un adulto che ha premuto per errore un pulsante di conferma. È correlato agli acquisti che non sono mai stati aperti né usati. È proprio per questo che i tuoi dati contano. Se i tuoi registri mostrano che il consumabile è stato consegnato per intero e ampiamente consumato, una richiesta di acquisto non intenzionale e un saldo interamente speso non concordano, e questo scarto vale la pena segnalarlo tramite consumptionPercentage.

FULFILLMENT_ISSUE rimanda a te

FULFILLMENT_ISSUE è l'unico motivo che riguarda in parte la tua app, non il cliente. Significa che dice di non essere riuscito a ricevere o usare ciò che ha pagato. Prima di contestare per riflesso, tira fuori i tuoi log di consegna. Se il tuo stesso server mostra che il diritto non si è mai attivato, o che i crediti non sono mai stati accreditati, il cliente ha ragione, e DECLINE è la preferenza sbagliata. Combattere un vero fallimento di consegna spreca la finestra e può spingere il cliente verso la sua banca, dove un chargeback costa più di quanto sarebbe costato il rimborso.

UNSATISFIED_WITH_PURCHASE è dove decidono le prove

Questo è il comune pentimento dell'acquirente, ed è il motivo in cui i tuoi dati di consumo fanno il lavoro più importante. Il prodotto ha funzionato. Il cliente ne ha usato una parte o tutto e ora vuole indietro i soldi. Un consumptionPercentage alto, un deliveryStatus onesto pari a DELIVERED e un refundPreference di DECLINE o GRANT_PRORATED è il caso che Apple ti chiede di presentare. Invia i numeri, non un'argomentazione.

LEGAL e OTHER

LEGAL significa che il cliente ha invocato un diritto legale o normativo. Le persone ragionevoli non sono d'accordo, ma di regola questa non è la finestra per fare causa. Concedilo e vai avanti. OTHER è il jolly che Apple usa quando il motivo dichiarato non corrisponde a nessuno dei quattro sopra. Non porta alcun segnale di per sé, quindi tratta un OTHER esattamente come tratteresti una richiesta senza alcun motivo: parti dal tuo stato di consegna e dalle tue prove di utilizzo.

Come il motivo cambia la tua risposta, campo per campo

Rispondi a un CONSUMPTION_REQUEST chiamando Send Consumption Information con un corpo ConsumptionRequest. Il motivo dovrebbe plasmare tre campi di quel corpo.

customerConsented deve essere true

Apple accetta l'invio solo quando customerConsented è true, cioè quando il cliente ha acconsentito a condividere i dati di consumo. Se non hai quel consenso, non puoi inviare alcun dato, indipendentemente dal motivo. Nessun consenso, nessuna prova, e la richiesta viene decisa senza i tuoi numeri.

deliveryStatus e consumptionPercentage portano i fatti

deliveryStatus indica se hai consegnato un acquisto funzionante. Se è qualcosa di diverso da DELIVERED, Apple richiede che consumptionPercentage sia 0. Quando hai davvero consegnato, consumptionPercentage è un intero in milliunits da 0 a 100,000, dove 100,000 significa che il cliente ha usato l'intero acquisto. Questa coppia è il tuo nucleo fattuale, ed è ciò che dovrebbe sostenere un caso FULFILLMENT_ISSUE o UNSATISFIED_WITH_PURCHASE, non il motivo in sé.

refundPreference è la tua unica leva

refundPreference è dove dichiari ciò che vuoi. Apple documenta tre valori: GRANT_FULL, GRANT_PRORATED e DECLINE. Leggi il motivo, valutalo rispetto ai tuoi dati, poi scegli. Un FULFILLMENT_ISSUE con una consegna fallita nei tuoi log pende verso GRANT_FULL. Un UNSATISFIED_WITH_PURCHASE su un prodotto interamente consumato pende verso DECLINE o GRANT_PRORATED. LEGAL pende verso GRANT_FULL.

Quanto ti costa davvero un rimborso

Il campo del motivo conta perché un rimborso è raramente solo la vendita che esce dal tuo bilancio. Per un consumabile già esaurito, hai pagato per adempierlo. Un pacchetto di crediti che ha chiamato un'API di inferenza a pagamento, un lotto di immagini generate che ha bruciato tempo di GPU, un export archiviato che pesa sulla tua fattura di storage, un pagamento a un creator che hai già inviato: quei costi restano spesi quando l'acquisto viene annullato. Lo store restituisce i soldi al cliente. Non ti restituisce il tuo calcolo.

Ecco perché vale la pena leggere il motivo. Poniamo che un cliente abbia comprato 5,000 crediti che ciascuno attiva una chiamata API a pagamento, ne abbia spesi 4,000 e poi abbia presentato la richiesta sotto UNSATISFIED_WITH_PURCHASE. Il tuo deliveryStatus è DELIVERED, il tuo consumptionPercentage è 80,000 milliunits, e una preferenza DECLINE o GRANT_PRORATED è la differenza tra incassare la fattura dell'API e recuperarne la maggior parte. Ora ribalta il motivo in FULFILLMENT_ISSUE con log che mostrano che i crediti non sono mai stati accreditati, e la mossa onesta e più economica è GRANT_FULL prima che il cliente si rivolga alla sua banca.

Leggere il motivo senza reagire in modo eccessivo

La trappola è trattare il motivo come una prova. UNINTENDED_PURCHASE non è una confessione che il prodotto sia rimasto inutilizzato, e LEGAL non è sempre una genuina richiesta legale. Il motivo restringe la situazione. I tuoi log di consegna e i tuoi registri di consumo la risolvono. Quando concordano con il cliente, concedi presto e a poco prezzo. Quando contraddicono il cliente, quella contraddizione, espressa come deliveryStatus e consumptionPercentage, è la cosa più forte che puoi inviare. RefundHalt legge consumptionRequestReason su ogni CONSUMPTION_REQUEST e lo abbina automaticamente ai tuoi dati di utilizzo reali, così ogni motivo riceve la risposta che merita entro la finestra di 12 hours.

Il cambiamento è piccolo e facile da non notare, ma ha spostato la conversazione sul rimborso a tuo favore. Apple ora ti dice il perché, prima che tu risponda. Usalo.