Un rimborso tramite l'Advanced Commerce API è l'unico modo in cui uno sviluppatore iOS può avviare un rimborso, e l'ultima parola spetta ancora ad Apple

Uno sviluppatore iOS comune non può rimborsare un cliente. A giugno 2026 un App Store Commerce Engineer ha risposto a una domanda sul forum degli sviluppatori con una sola frase: al momento uno sviluppatore non può emettere direttamente un rimborso. C'è un'eccezione, e si trova dentro l'Advanced Commerce API. Le app che Apple approva possono inviare una richiesta di rimborso tramite l'Advanced Commerce API, revocare un abbonamento con restituzione del denaro o chiedere un importo personalizzato. Apple decide comunque se il denaro viene restituito.

Che cos'è l'Advanced Commerce API e chi può usarla

Apple ha rilasciato l'Advanced Commerce API il 23 gennaio 2025. Gestisce gli acquisti In-App di Apple per cataloghi eccezionalmente ampi di acquisti singoli personalizzati, abbonamenti e abbonamenti con componenti aggiuntivi opzionali. Non crei ogni prodotto in App Store Connect. Definisci gli SKU sul tuo server e li invii ad Apple al momento dell'acquisto.

L'accesso viene concesso app per app. Compili un modulo di richiesta, e la pagina dei requisiti di Apple indica tre modelli di business che devono essere centrali nell'app:

• Cataloghi eccezionalmente ampi di acquisti singoli, come audiolibri, lezioni, corsi o mini app.
• Cataloghi eccezionalmente ampi di contenuti in abbonamento, dove l'offerta di ogni creator è un abbonamento a sé.
• Un abbonamento con componenti aggiuntivi opzionali che si rinnovano insieme come un unico acquisto, come canali premium o sport.

Apple consente di candidarsi anche quando un altro programma richiede l'API. Il Mini Apps Partner Program, che paga ai membri l'85% delle vendite In-App idonee nelle mini app ospitate, la richiede.

Gli endpoint di rimborso sono arrivati dopo, e richiedono una firma

La versione 1.1, datata 24 marzo 2025, ha aggiunto Request Transaction Refund e Revoke Subscription. La pagina del programma di Apple dice che le app che offrono contenuti in abbonamento possono anche essere idonee a usare le API Cancel, Revoke e Refund per gestire le disdette, convalidare i contenuti dopo l'acquisto e amministrare i propri cataloghi. Ogni pagina di endpoint aggiunge la stessa condizione: il tuo Account Holder deve firmare l'Advanced Commerce API Addendum, e se l'ultima versione non è accettata, la chiamata restituisce un errore. È l'Addendum, non la documentazione, a elencare i casi d'uso previsti per ogni endpoint.

I tre endpoint, a confronto

Cancel a Subscription blocca il prossimo addebito

Cancel disattiva il rinnovo automatico. Apple dice che il cliente mantiene l'accesso fino alla fine del periodo in corso. Non viene rimborsato nulla. È la scelta giusta quando un cliente vuole andarsene e ha già usato il tempo che ha pagato.

Revoke Subscription chiude tutto subito

Revoke imposta il rinnovo automatico su false e revoca l'abbonamento con un rimborso totale o proporzionale. Il corpo della richiesta accetta refundReason, refundRiskingPreference, refundType e requestInfo. Apple invia poi una notifica REFUND al tuo endpoint App Store Server Notifications V2. L'indicazione di Apple è precisa: interrompi il servizio a partire dalla revocationDate di quella notifica, e non interromperlo prima che la notifica arrivi.

Request Transaction Refund lavora elemento per elemento

Questo è lo strumento di precisione. Invii un elenco di elementi, e ognuno indica uno SKU, un refundReason, un refundType e un flag revoke. Con CUSTOM invii anche refundAmount in millesimi della valuta, quindi 4990 significa 4,99. Se invii un importo con FULL o PRORATED, Apple lo rifiuta con l'errore 4000155. La risposta contiene una transazione firmata e, per gli abbonamenti, le informazioni di rinnovo firmate.

Apple accetta questi valori di refundReason: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL, OTHER e MODIFY_ITEMS_REFUND. Un settimo, SIMULATE_REFUND_DECLINE, serve solo per i test in sandbox e su TestFlight, ed esiste perché l'App Store può dire di no.

Apple può ancora rifiutare la tua stessa richiesta di rimborso

Il nome dell'endpoint è onesto. È una richiesta. Due campi mostrano dove sta davvero la decisione.

refundRiskingPreference apre la porta a un controllo sui consumi

Apple descrive refundRiskingPreference come l'impostazione che stabilisce se l'App Store ti chiede dati di consumo per orientare la decisione sul rimborso. Il valore predefinito è true. Quando è true, ricevi un CONSUMPTION_REQUEST per la tua stessa richiesta di rimborso e rispondi tramite Send Consumption Information. Apple chiede agli sviluppatori di rispondere entro 12 ore dalla ricezione di un CONSUMPTION_REQUEST. Impostalo su false e quella notifica non arriva.

Gli errori che ti dicono di no

PendingRefundError è quello da mettere in conto. Una causa probabile è un cliente che ha già chiesto ad Apple tramite Report a Problem prima che il tuo team di assistenza intervenisse. Le regole di idoneità di Apple impongono comunque a queste app di offrire un percorso interno all'app per il rimborso, cioè un link a Report a Problem oppure l'API beginRefundRequest, quindi entrambe le porte restano aperte contemporaneamente.

Quanto ti costa in denaro un rimborso tramite l'Advanced Commerce API

Rimborsare di tua iniziativa sembra più economico che combattere una contestazione. Restano comunque soldi in uscita, e l'API rende facile ripetere alcuni errori su larga scala.

Le imposte dentro l'importo personalizzato

Apple dice che un refundAmount richiesto deve includere le imposte in tutte le regioni tranne Canada e Stati Uniti. Un team che calcola un rimborso CUSTOM partendo dal prezzo dello SKU al netto delle imposte rimborserà meno del dovuto ai clienti di tutti gli altri storefront, e poi pagherà tempo di assistenza per correggere ogni caso.

Costi che non tornano indietro

• Compensi: in un catalogo di creator o in una piattaforma di mini app, la quota del creator viene spesso pagata al momento della vendita. Un rimborso al cliente non la recupera.
• Licenze dei contenuti: i compensi per titolo dovuti a un titolare dei diritti per un audiolibro o un corso possono scattare con l'accesso, a seconda del contratto, e un rimborso non li annulla.
• Calcolo: streaming, transcodifica e qualsiasi lavoro lato server svolto per l'acquisto sono già nella tua fattura.
• Chiamate API: i servizi di terzi fatturati a richiesta, dalla sintesi vocale all'inferenza dei modelli, restano fatturati dopo il rimborso.

Totale quando intendevi un solo elemento

Revoke Subscription rimborsa e chiude l'intero abbonamento, componenti aggiuntivi compresi. Se il cliente contesta un solo componente aggiuntivo, Request Transaction Refund ti permette di rimborsare solo quello SKU, con revoke attivo solo per quell'elemento. Chiamare Revoke Subscription per un reclamo su un solo elemento restituisce anche i ricavi del piano base.

Una checklist prima di attivare queste chiamate

• Verifica che il tuo Account Holder abbia accettato l'Advanced Commerce API Addendum in vigore, e imposta un avviso sull'errore che compare quando scade.
• Genera un nuovo requestReferenceId UUID per ogni richiesta, e riusa lo stesso solo per ritentare una chiamata andata in timeout.
• Metti in coda le chiamate di rimborso. Il limite è di 5 al secondo per app, e una risposta 429 contiene un header Retry-After in millisecondi UNIX.
• Testa i rifiuti in sandbox con SIMULATE_REFUND_DECLINE, e ricorda che i limiti della sandbox sono il 10 per cento di quelli di produzione.
• Decidi refundRiskingPreference caso per caso, e tieni pronto un risponditore sui consumi per la finestra di 12 ore quando resta true.
• Interrompi l'accesso solo quando arriva la notifica REFUND, a partire dalla sua revocationDate.
• Registra motivo, importo e SKU di ogni richiesta, così il tuo tasso di rimborso è visibile a te prima che lo veda Apple.