Se la tua app usa ancora App Store Server Notifications V1, Apple non ti consulta mai sui rimborsi degli abbonamenti

La versione 1 di App Store Server Notifications consegna ancora i rimborsi, ma esclude l'unica notifica che ti permette di far valere le tue ragioni su un rimborso di abbonamento. Apple ha deprecato V1 il 5 giugno 2023, insieme all'endpoint verifyReceipt, e da allora ha aggiunto ogni funzionalità legata ai rimborsi solo a V2. Se le impostazioni di App Store Connect indicano ancora Version 1, Apple può decidere un rimborso di abbonamento senza mai inviare un CONSUMPTION_REQUEST al tuo server. Non perdi una contestazione. Non vieni mai invitato a parteciparvi.

Cosa significa la deprecazione di App Store Server Notifications V1 da parte di Apple

Deprecato non significa spento. Un ingegnere di Apple ha scritto sui forum per sviluppatori a giugno 2023 che verifyReceipt e le notifiche V1 avrebbero continuato a funzionare fino all'annuncio di una data di dismissione, che quella data non era stata fissata e che gli sviluppatori sarebbero stati avvisati in anticipo. Più di tre anni dopo, App Store Connect offre ancora "Version 1 (deprecated)" come opzione quando imposti l'URL del server.

Ciò che la deprecazione significa davvero è un congelamento. Ogni modifica nel changelog delle notifiche di Apple da giugno 2023 riguarda V2: nuovi campi nella transazione firmata, nuovi tipi di notifica, i dati sull'impegno di 12 mesi aggiunti ad aprile 2026. Un server V1 non vede nulla di tutto questo.

Quali segnali di rimborso un server V1 non riceve mai

Ecco come gli stessi eventi di rimborso raggiungono un server V1 e un server V2, secondo la documentazione di Apple per ciascuna versione.

V1 riceve ancora CONSUMPTION_REQUEST?

Sì, per i consumabili. Il riferimento V1 di Apple descrive CONSUMPTION_REQUEST come la notifica inviata quando un cliente avvia una richiesta di rimborso per un acquisto in-app consumabile. Un ingegnere di Apple ha confermato sui forum nel 2023 che le richieste di consumo V1 vengono inviate per i rimborsi idonei. La lacuna riguarda gli abbonamenti. Il changelog di Apple data le richieste di consumo per gli abbonamenti all'11 aprile 2024, in V2, e la documentazione di Send Consumption Information indica che Apple invia la richiesta tramite il tuo endpoint V2.

Perché CANCEL in V1 è facile da fraintendere

In V1, quando Apple rimborsa un abbonamento, il tipo di notifica è CANCEL, spesso accompagnato da DID_CHANGE_RENEWAL_STATUS. Molti server trattano qualsiasi cancellazione come un cliente che disattiva il rinnovo automatico, lasciando l'accesso attivo fino alla fine del periodo. V2 elimina l'ambiguità. Un rimborso arriva come REFUND, e un cliente che disattiva il rinnovo arriva come DID_CHANGE_RENEWAL_STATUS con il sottotipo AUTO_RENEW_DISABLED.

Quanto costa, in denaro, restare su V1

Apple decide ogni rimborso dell'App Store. Il CONSUMPTION_REQUEST è l'unico momento in cui i tuoi dati di utilizzo raggiungono quella decisione, e Apple ti chiede di rispondere entro 12 ore. In V1, i rimborsi degli abbonamenti saltano questo passaggio.

Ecco un esempio con numeri indicativi. Supponiamo che la tua app venda un abbonamento mensile da $9.99 che include generazioni di immagini con IA. Un abbonato esegue 400 generazioni in un mese, e ognuna ti costa denaro reale in inferenza del modello. Poi chiede un rimborso ad Apple.

Il pagamento che perdi è la tua quota, non il prezzo di listino. Apple versa il 70% del prezzo di un abbonamento, al netto delle imposte applicabili, durante il primo anno di servizio a pagamento di un abbonato, e l'85% dopo quel periodo o per i membri dell'App Store Small Business Program. La bolletta del calcolo non si riduce di conseguenza. Inferenza, chiamate ad API di terze parti e storage dei file sono stati pagati quando il cliente li ha usati.

Anche le due notifiche di esito mancanti costano denaro. Senza REFUND_REVERSED, un server che ha revocato l'accesso a seguito di un rimborso non lo ripristina mai quando Apple annulla il rimborso, così un cliente pagante resta bloccato e scrive all'assistenza. Senza REFUND_DECLINED, non puoi distinguere un rimborso ancora in sospeso da uno che Apple ha rifiutato.

Come migrare da V1 a V2 senza perdere nessun rimborso

Passare a V2 richiede una modifica al server più un'impostazione. Le indicazioni di Apple stessa sui forum, fornite da un App Store Commerce Engineer a dicembre 2025, spiegano cosa succede il giorno del passaggio.

Crea l'endpoint V2 prima di cambiare l'impostazione

• Accetta un POST il cui corpo contiene un signedPayload. I payload V2 sono JWS firmati da Apple, quindi verifica la firma prima di fidarti di qualsiasi contenuto. L'App Store Server Library di Apple lo fa per te.
• Sposta la gestione di CANCEL su REFUND, e gestisci REFUND_DECLINED e REFUND_REVERSED come nuovi casi.
• Rispondi al CONSUMPTION_REQUEST degli abbonamenti con Send Consumption Information, e solo quando il cliente ha acconsentito alla condivisione dei dati con Apple. Apple specifica che senza consenso non devi rispondere.
• Restituisci HTTP da 200 a 206 in caso di successo. Qualsiasi 40x o 50x fa sì che Apple ritenti.

Cambia l'impostazione in App Store Connect

In App Store Connect, apri la tua app, scegli App Information sotto General, individua App Store Server Notifications e imposta la Production Server URL sul tuo endpoint V2 con Version 2 selezionata. Fai prima lo stesso con l'URL di sandbox se vuoi testare, e usa Request a Test Notification per verificare che il tuo server risponda.

Mantieni attivo il gestore V1 per circa tre giorni

Dopo il passaggio, le nuove notifiche arrivano subito in formato V2, per tutti gli abbonamenti, vecchi o nuovi. Le notifiche V1 già in fase di ritentativo continuano ad arrivare in formato V1 finché non vanno a buon fine o esauriscono i tentativi. Apple colloca l'ultimo tentativo V1 possibile a circa 78 ore, cioè 6 più 24 più 48. Lascia in funzione il vecchio gestore oltre questo intervallo, poi rimuovilo.

Già che ci sei, sostituisci verifyReceipt

verifyReceipt è stato deprecato lo stesso giorno. Risponde ancora, ma Apple indirizza i server verso l'App Store Server API. Get Transaction Info restituisce una transazione firmata, Get Transaction History restituisce lo storico di un cliente e Get Refund History elenca tutti gli acquisti rimborsati di un cliente. Insieme alle notifiche V2, coprono ciò per cui la maggior parte dei server usava le ricevute, compreso il campo cancellation_date che un tempo segnalava un rimborso in una ricevuta.

RefundHalt si collega ad App Store Server Notifications V2 e risponde a ogni CONSUMPTION_REQUEST entro la finestra di 12 ore, usando i dati di utilizzo che la tua app registra già. Se sei ancora su V1, il passaggio è il primo requisito per rendere possibile tutto questo.