La Retention Messaging API di Apple mette le tue parole nella schermata di disdetta, ma le richieste di rimborso non ci passano mai

Agli abbonati che toccano Annulla su un iPhone ora si può mostrare, prima della conferma, un messaggio scelto da te, un piano più economico o uno sconto. È la Retention Messaging API di Apple, ed è la prima volta che uno sviluppatore ha voce in capitolo sulla schermata di disdetta di Apple stessa. È ancora una versione preliminare a cui bisogna chiedere di accedere. Ha anche un confine netto che conta se ti interessano i rimborsi: parla a chi sta per smettere di pagare, non a chi chiede indietro i propri soldi. Quelle richieste arrivano ad Apple per un'altra strada.

Cosa fa la Retention Messaging API di Apple

La Retention Messaging API è un servizio da server a server. Carichi in anticipo su Apple testi e immagini dei messaggi, Apple li esamina, e poi scegli quale messaggio approvato vede un abbonato quando sta per disdire un abbonamento a rinnovo automatico. La documentazione di Apple elenca quattro tipi di messaggio:

• Un messaggio di testo, che può includere elenchi puntati.
• Un messaggio di testo con immagine.
• Un messaggio di cambio piano, che suggerisce un altro abbonamento dello stesso gruppo di abbonamenti.
• Un messaggio di offerta promozionale, che propone un prezzo scontato allo stesso livello o a un altro, usando un'offerta promozionale che configuri in App Store Connect e firmi sul tuo server.

Il messaggio compare dopo che il cliente ha toccato Cancel Subscription in una pagina di dettagli dell'abbonamento. Apple mostra poi una pagina Confirm Cancellation (Conferma annullamento). Il cliente può ancora disdire, toccare Keep Subscription (Mantieni abbonamento) o accettare l'offerta o il piano che hai suggerito. Non puoi nascondere l'uscita, e Apple chiede agli sviluppatori di non caricare contenuti fuorvianti o inesatti.

Messaggi predefiniti e flusso in tempo reale

Ci sono due modi di usarla. Quello semplice sono i messaggi predefiniti: testo, con o senza immagine o elenco puntato, assegnato a ogni prodotto e lingua. Quello più ricco è il flusso in tempo reale, in cui Apple chiama un endpoint Get Retention Message sul tuo server e tu rispondi con un ID messaggio. Solo il flusso in tempo reale può mostrare messaggi di cambio piano e di offerta promozionale.

In pratica i messaggi predefiniti non sono facoltativi. Apple li usa come ripiego ogni volta che una chiamata in tempo reale fallisce, e non mostra alcun messaggio di retention per un prodotto in una lingua che non ha un predefinito.

Cosa comunica Apple al tuo server nella chiamata in tempo reale

La richiesta è un JWS firmato dall'App Store. Una volta decodificata, contiene originalTransactionId, appAppleId, productId, userLocale, un requestIdentifier UUID, l'ambiente e signedDate. Apple ti chiede di verificare che appAppleId corrisponda alla tua app e di non rispondere se non corrisponde. La parte utile è originalTransactionId, perché ti permette di vedere cosa ha fatto davvero questo abbonato nella tua app prima di scegliere cosa dirgli.

Dove compare il messaggio di retention, e dove no

Apple colloca il messaggio in una sola schermata, il passaggio Confirm Cancellation dopo che il cliente ha toccato Cancel Subscription, per esempio da Apple Account > Subscriptions o dalla pagina di un abbonamento nell'App Store. Quella schermata riguarda se ci sarà il prossimo rinnovo. Non tocca il denaro già incassato.

Una richiesta di rimborso è un atto separato. La pagina di supporto di Apple manda i clienti su reportaproblem.apple.com, dove scelgono “Request a refund” (Richiedi un rimborso), selezionano un motivo e un articolo, e aspettano da 24 a 48 ore un aggiornamento. Dentro la tua app, beginRefundRequest di StoreKit apre il pannello di rimborso di Apple, e Apple dice che l'App Store impiega fino a 48 ore per approvare o rifiutare. Nessuno dei due percorsi passa dalla schermata Confirm Cancellation.

Un messaggio di retention può fermare una richiesta di rimborso?

No. La richiesta di rimborso non arriva mai alla schermata in cui vive il messaggio. Un dettaglio nella documentazione delle notifiche di Apple lo rende concreto. Quando un cliente chiede un rimborso dalla tua app con l'API di richiesta di rimborso, Apple disattiva da sola il rinnovo automatico e invia DID_CHANGE_RENEWAL_STATUS con il sottotipo AUTO_RENEW_DISABLED. Un cliente che disdice dalla pagina delle impostazioni Abbonamenti produce lo stesso tipo e sottotipo. Il tuo server vede una sola notifica per due clienti molto diversi, e solo uno dei due ha visto il tuo messaggio di retention.

Se la richiesta di rimborso va avanti, il canale delle prove è il CONSUMPTION_REQUEST. Apple lo invia per le richieste di rimborso su qualsiasi tipo di prodotto, e hai 12 ore per rispondere con Send Consumption Information. Puoi rispondere solo se il cliente ha dato il consenso. Dopo, la decisione di Apple arriva come notifica REFUND, oppure come REFUND_DECLINED se Apple rifiuta un rimborso che il cliente ha avviato nella tua app.

Google Play ha un'API per i messaggi di disdetta?

Non nella documentazione di Google sul ciclo di vita degli abbonamenti. Un abbonato Google Play disdice dal centro abbonamenti di Play, mantiene l'accesso fino alla fine del ciclo di fatturazione in corso e può toccare Resubscribe (Abbonati di nuovo) per annullare la disdetta prima di allora, cosa che Google chiama ripristino. Lo scopri dopo, tramite una notifica SUBSCRIPTION_CANCELED, e il campo userInitiatedCancellation nella risorsa dell'abbonamento ti dice perché l'utente se n'è andato. La pausa, che secondo Google è attiva per impostazione predefinita su tutti gli abbonamenti, è il suo principale strumento integrato per ridurre l'abbandono volontario.

Sul fronte dei rimborsi, Google Play ha un proprio canale delle prove. Arriva una PendingRefundReviewNotification quando uno storno richiede la revisione dello sviluppatore, e hai 24 ore per rispondere tramite orders.reviewrefund. Per gli ordini effettuati dopo il 3 agosto 2026, quando uno storno va a buon fine, Google addebita allo sviluppatore il prezzo d'acquisto, al netto della commissione di servizio di Play, più le commissioni di storno della banca.

Quanto ti costa in denaro la schermata di disdetta

I messaggi di retention sembrano gratuiti. Non lo sono, e i conti arrivano da tre parti.

Calcolo a ogni visualizzazione di pagina

Apple chiama il tuo endpoint quando un abbonato attivo apre una pagina di dettagli dell'abbonamento con un pulsante Annulla, non solo quando disdice. Ogni visita è una richiesta che il tuo server deve autenticare, elaborare e a cui deve rispondere entro 700 ms, altrimenti Apple ripiega sul predefinito. Questo esclude una funzione con avvio a freddo che a volte impiega due secondi. Paghi una capacità sempre pronta, più le letture dal database e le chiamate a pagamento ad API di terze parti che la tua logica decisionale esegue a ogni richiesta.

Lo sconto è un ricavo che hai scelto di non incassare

Un'offerta promozionale che trattiene un abbonato è denaro vero conservato. Una che va a chi sarebbe rimasto comunque è puro sconto. Questo è un esempio, non un benchmark. Un piano mensile da 9,99 $ offerto a metà prezzo per tre mesi rinuncia a 14,99 $ per ogni offerta accettata. Se una persona su tre tra quelle che accettano sarebbe rimasta a prezzo pieno, mille accettazioni costano circa 5.000 $ di sconti dati a persone che non ne avevano bisogno. L'altro lato del bilancio sono gli abbonati che se ne stavano davvero andando.

Il rimborso che un'uscita sgradevole provoca

Apple lascia il pulsante Cancel Subscription sulla pagina, quindi non puoi intrappolare nessuno, ma puoi comunque risultare fastidioso. Un cliente che si sente spinto ha un'altra opzione: chiedere ad Apple di restituirgli l'ultimo addebito. Quando arriva un rimborso, il denaro torna indietro, mentre calcolo, archiviazione, chiamate API ed eventuali compensi agli affiliati legati a quell'abbonato restano spesi. Sono costi che nessun messaggio di retention recupera.

Come usare i messaggi di retention senza alzare il tasso di rimborsi

Tratta la schermata di disdetta come un posto in cui essere precisi, non furbi. Poche regole la tengono dal lato giusto della linea dei rimborsi:

• Decidi abbonato per abbonato. Usa l'originalTransactionId nella richiesta di Apple per controllare l'utilizzo recente. Offri uno sconto o un piano più economico a chi usa il prodotto. Mostra un messaggio breve e onesto a chi non lo apre da settimane.
• Rispondi in fretta. Calcola la decisione in anticipo quando cambiano i tuoi dati di utilizzo, così la richiesta stessa è una singola lettura che sta ampiamente entro 700 ms.
• Scrivi un messaggio predefinito per ogni prodotto e lingua. Senza, una chiamata fallita significa nessun messaggio.
• Tieni d'occhio AUTO_RENEW_DISABLED. Se segue un CONSUMPTION_REQUEST per lo stesso originalTransactionId, sei davanti a una richiesta di rimborso, non a una disdetta, e il conto alla rovescia di 12 ore è partito.
• Rispondi a ogni CONSUMPTION_REQUEST a cui puoi rispondere. RefundHalt invia ad Apple dati di consumo accurati entro la finestra di 12 ore e risponde alla revisione degli storni di Google Play entro 24 ore, perché sono gli unici due momenti in cui uno dei due store chiede la tua versione.

Vale la pena chiedere l'accesso ad Apple?

Se vendi abbonamenti a rinnovo automatico e gestisci già le App Store Server Notifications V2, probabilmente sì. La schermata di disdetta è l'ultimo punto in cui puoi raggiungere un abbonato prima che se ne vada, e un cambio di piano ti costa meno che perderlo del tutto. Metti solo in conto un endpoint che risponda a ogni visualizzazione di una pagina di abbonamento, e tieni le tue difese contro i rimborsi dove i rimborsi avvengono davvero.