Il Send Consumption Information di Apple ora chiede cinque campi, non dodici, ed ecco ciascuno di essi

L'elenco dei fatti che Apple ti chiede quando un cliente vuole un rimborso è diventato molto più corto. Il payload di Send Consumption Information, l'unica risposta che uno sviluppatore può portare a una decisione di rimborso dell'App Store, aveva dodici campi. Ora ne ha cinque. Apple lo ha sfoltito intorno alla WWDC24 e ha condensato la maggior parte delle vecchie domande di profilazione dell'account in due semplici e un numero. Meno campi non è una modifica da poco. Cambia quali prove Apple pesa e cambia quali campi non ti puoi permettere di sbagliare.

Ecco perché merita la tua attenzione e non è solo una nota sullo schema. Questo payload è l'unico momento in un rimborso Apple in cui la tua versione dei fatti raggiunge la decisione. Un rimborso di un consumabile annulla ricavi che hai già speso denaro reale per consegnare, e i cinque campi sono il modo in cui dici ad Apple che il prodotto è stato consegnato e usato. Perdi la finestra di 12 ore o compili male un campo, e Apple decide sulla sola richiesta del cliente.

Cos'è Send Consumption Information

Send Consumption Information è l'endpoint della App Store Server API che chiami dopo che Apple ha inviato al tuo server una notifica CONSUMPTION_REQUEST. Quella notifica significa che un cliente ha chiesto ad Apple un rimborso su un acquisto in-app e Apple vuole il tuo contributo prima di decidere. Rispondi inviando con un PUT un piccolo corpo JSON, il ConsumptionRequest, all'endpoint. Apple lo legge, lo pesa rispetto alla cronologia del cliente e prende la decisione. Non decidi mai tu il rimborso. Tu fornisci fatti.

Il corpo è l'intera interfaccia. Non c'è un modulo separato, nessun ricorso, nessun secondo invio che conti. Quello che invii in quell'unico payload è il tuo caso completo, quindi il significato di ogni campo conta più di quanto il numero di campi suggerisca.

I cinque campi che Apple chiede ora

Il ConsumptionRequest attuale ha cinque membri. Tre sono obbligatori e due sono facoltativi. Tutto ciò che Apple chiedeva sull'account del cliente, la sua anzianità, la spesa complessiva, i rimborsi complessivi, il tempo di gioco, è stato rimosso da ciò che invii.

customerConsented è la barriera

customerConsented è un booleano, ed è il campo che decide se invii qualcosa. Registra se il cliente ha accettato che tu condivida i dati di consumo con Apple. L'indicazione di Apple è diretta: se il cliente non ha dato il consenso, non inviare le informazioni di consumo. Quindi non è un campo che imposti su true per rafforzare il tuo caso. Riflette un sì o no reale che devi già avere, e un false qui significa che il resto del payload non va inviato.

deliveryStatus è il campo che muove i rimborsi

deliveryStatus è un enum di stringa, ed è la leva più forte che hai. Dice ad Apple se la tua app ha davvero consegnato un acquisto in-app funzionante. Un valore dice sì. Gli altri quattro dicono no, ciascuno per un motivo diverso, e ognuno dice ad Apple che il cliente ha una lamentela legittima.

sampleContentProvided risponde a una questione di equità

sampleContentProvided è un booleano. Registra se hai dato al cliente un campione gratuito, una prova o informazioni chiare su cosa fa l'acquisto prima che comprasse. Un true qui è un piccolo segnale di equità: il cliente ha avuto la possibilità di sapere cosa stava comprando. Non decide nulla da solo, ma è uno dei soli tre campi obbligatori, quindi Apple lo vuole chiaramente in ogni risposta.

consumptionPercentage ora è un numero, non uno stato

Questo è il campo che è cambiato di più. Il vecchio payload aveva consumptionStatus, un enum a quattro passi: UNDECLARED, NOT_CONSUMED, PARTIALLY_CONSUMED, FULLY_CONSUMED. Il nuovo payload lo sostituisce con consumptionPercentage, un intero misurato in milliunits. 100,000 milliunits significa che l'articolo è stato consumato del tutto, quindi 50,000 è la metà e 0 è intatto. Un numero preciso batte un secchio a quattro scelte, perché ti consente di dire che un cliente ha bruciato il 90 per cento di un pacchetto di crediti invece di arrotondare per difetto a consumato parzialmente.

Un'avvertenza che confonde le persone. Per gli abbonamenti a rinnovo automatico Apple calcola il consumo da sola in base al tempo trascorso, quindi consumptionPercentage è pensato per acquisti consumabili e non rinnovabili. Invialo dove si applica, e lascia che Apple lo ricavi dove non si applica.

refundPreference esprime una preferenza, non un verdetto

refundPreference è una stringa facoltativa, ed è dove dici ad Apple quale esito preferiresti. Anche questo ha cambiato forma. Il vecchio campo era un numero con valori come prefer-grant, prefer-decline e no-preference. Il nuovo è una stringa con nome a tre valori.

Cosa ha eliminato Apple, e perché conta

Il vecchio ConsumptionRequest aveva dodici campi. Sette di essi sono spariti da ciò che invii. accountTenure, lifetimeDollarsPurchased, lifetimeDollarsRefunded, playTime, userStatus, platform e appAccountToken erano la metà di profilazione dell'account del payload, i campi che ti chiedevano di classificare un cliente in base a da quanto tempo aveva un account, quanto aveva speso, quanto era stato rimborsato e da quanto tempo usava l'app.

Apple li ha eliminati per un motivo che vale la pena notare. Quei campi chiedevano agli sviluppatori di consegnare un profilo del cliente, e la maggior parte degli sviluppatori li lasciava non dichiarati oppure li indovinava. I cinque che restano riguardano l'acquisto e la consegna, fatti che puoi davvero verificare dai tuoi sistemi. Il passaggio va da chi è il cliente a cosa è successo con questo specifico acquisto.

L'endpoint e l'orologio

Invii il payload con un PUT HTTP all'endpoint di Send Consumption Information, identificato dall'id della transazione dell'acquisto contestato: PUT /inApps/v1/transactions/consumption/{transactionId}. Un successo restituisce 202 Accepted, e il corpo della risposta è vuoto. Quella risposta vuota è attesa, non un bug. Conferma che Apple ha messo in coda i tuoi dati, e non ti dice nulla sull'esito finale, che arriva più tardi come notifica REFUND o REFUND_DECLINED.

L'orologio è la parte che non puoi allungare. Apple ti dà 12 ore dal CONSUMPTION_REQUEST per rispondere. Viene usata solo la tua prima risposta, quindi il primo payload deve essere quello completo e corretto. Apple può inviare il CONSUMPTION_REQUEST più di una volta per lo stesso acquisto, ma la scadenza di ciascuno è fissa, e una revisione manuale raramente rientra in 12 ore tra fusi orari e fine settimana.

Cosa ti costa un campo gestito male

Il denaro ha lasciato l'edificio prima del rimborso

Il rimborso di un consumabile non è un'annullamento pulito. Quando un cliente chiede indietro i soldi per un pacchetto di crediti o un lotto di generazioni di IA, hai già speso per consegnarlo: inferenza GPU su ogni richiesta, chiamate ad API di modelli di terze parti fatturate a token, archiviazione di ciò che hai prodotto, e qualsiasi pagamento a creator o partner legato a quell'uso. Il prezzo del negozio torna al cliente. Il tuo costo di consegna non torna a te. Quindi un rimborso che avresti potuto contestare non è un evento in pareggio, è una perdita netta di tutto ciò che hai pagato per servire l'account.

I cinque campi sono il modo per evitare di pagare due volte

deliveryStatus impostato su DELIVERED e un consumptionPercentage alto sono i due fatti che dicono ad Apple che il cliente ha ricevuto e usato il prodotto. Sono la tua prova che il calcolo, le chiamate all'API e l'archiviazione hanno fatto il loro lavoro. Lascia il payload non inviato e Apple non lo viene mai a sapere. Decide dalla richiesta del cliente, il rimborso è più probabile che passi, e tu ti accolli sia i ricavi annullati sia il costo di consegna dietro di essi.

I chargeback sono la porta peggiore, e il silenzio punta a essa

Un cliente che non ottiene soddisfazione tramite il flusso di rimborso di Apple può comunque contestare l'addebito con la sua banca. Un chargeback di carta è definitivo, comporta una commissione di contestazione fissa, e toglie la decisione dalle mani di Apple e dalle tue. Rispondere bene al CONSUMPTION_REQUEST tiene la contestazione dentro il sistema di Apple, dove hai voce. Ignorarlo spinge i casi limite verso l'unico canale dove non ne hai nessuna.

Come lo gestisce RefundHalt

I cinque campi sembrano semplici finché non devi compilarli correttamente, entro 12 ore, a ogni CONSUMPTION_REQUEST, legati alla transazione giusta. RefundHalt intercetta la notifica, legge i tuoi registri di consegna e uso per quell'acquisto, e invia il payload automaticamente prima che la finestra si chiuda. deliveryStatus riflette ciò che i tuoi log mostrano davvero, consumptionPercentage viene dall'uso reale invece che da un'ipotesi, e refundPreference segue la policy che hai impostato una volta. Ottieni il rimborso contestabile esaminato con prove, non una scadenza mancata e una decisione presa senza di te.