Retention Messaging API: je bericht vóór het opzeggen

De Retention Messaging API is een server-to-server-dienst van Apple die jouw bericht aan een abonnee toont op het moment dat hij op Cancel Subscription tikt. Het bericht verschijnt op een bevestigingspagina, voordat de opzegging definitief is. Het kan de waarde van je abonnement in herinnering brengen, een ander abonnement of een promotieaanbieding voorstellen, maar de knop om op te zeggen blijft altijd staan. De API is sinds juli 2025 een preview, op aanvraag, en Apple heeft een eenvoudigere versie in App Store Connect aangekondigd voor het najaar van 2026.

Deze gids legt uit wat de API toont, sinds wanneer hij bestaat, wie hem mag gebruiken, welke voorwaarden er gelden en hoe je hem instelt. Alles komt uit de documentatie van Apple en de WWDC26-sessie erover, nagelezen op 3 november 2026.

Ik verkoop abonnementen in mijn iOS-apps: Solys, een blocker voor sociale media, TradaZen, een tradingsimulator, Nolera, een app om outfits met AI te passen, en Vigie. Op 25 oktober 2026 heb ik voor alle vier toegang tot de API aangevraagd en hun berichten in al hun talen voorbereid. Op 28 oktober was het akkoord van Apple er nog niet: deze gids beschrijft dus de regels en mijn voorbereiding, nog geen resultaten.

Wat de Retention Messaging API doet

Volgens de documentatie van Apple kies je met de API het bericht dat het systeem toont wanneer een klant de detailpagina van een abonnement bekijkt en misschien op het punt staat op te zeggen. Je bereidt je berichten van tevoren voor, per product en per taal.

Het verloop is altijd hetzelfde:

1. De abonnee opent zijn abonnement, bijvoorbeeld via Apple Account, Subscriptions, of vanuit de App Store.
2. Hij tikt op Cancel Subscription.
3. Het systeem toont een bevestigingspagina (Confirm Cancellation), met jouw bericht.
4. Hij kan alsnog opzeggen, zijn abonnement houden, of ingaan op wat je bericht voorstelt.

Het bericht is zichtbaar op iOS 15.1 en iPadOS 15.1 of nieuwer, op visionOS 1 en op macOS 14 of nieuwer.

Sinds wanneer, en voor wie

Datum	Wat er verandert, volgens Apple
16 jul. 2025	Versie 1.0: eerste preview van de API
9 dec. 2025	Prestatietest van de server voor realtime
31 mrt. 2026	Opsommingstekens in berichten, realtime-adres instellen via de API
27 apr. 2026	Ondersteuning voor maandabonnementen met een verplichting van 12 maanden
Juni 2026	WWDC26: aankondiging van een module in App Store Connect

De datums komen uit de changelog van de API, behalve de laatste, die uit de WWDC26-sessie komt. De API is nog steeds een preview: de documentatie verwijst naar een aanvraagformulier, waarvoor je moet inloggen met je developeraccount.

Op WWDC26 presenteert de sessie Explore Retention Messaging in App Store Connect een module die je zonder code instelt, in App Store Connect. Apple noemt hem "voor iedereen beschikbaar". De realtime-versie blijft wel op aanvraag. De pagina met nieuws over de App Store kondigt de module aan voor "dit najaar". Op 3 november 2026 heeft de help van App Store Connect er nog geen enkele pagina over, en op 28 oktober stond de module nog niet in mijn account.

De API is bedoeld voor apps die een automatisch verlengbaar abonnement verkopen. Hij is niet alleen voor grote uitgevers: RevenueCat merkt in zijn onderzoek naar 22 miljoen berichten op dat kleine apps ook toegang kunnen aanvragen.

De 4 soorten berichten

Soort	Wat de abonnee ziet	Standaardbericht	Realtime
Tekst	Een titel, een tekst, tot vijf opsommingstekens	Ja	Ja
Tekst met afbeelding	Hetzelfde, met een afbeelding	Ja	Ja
Ander abonnement	Een tekst en een ander abonnement uit dezelfde groep	Nee	Ja
Promotieaanbieding	Een tekst en een aanbieding om met korting door te gaan	Nee	Ja

Volgens de pagina over het voorbereiden van berichten kan een standaardbericht alleen een tekst zijn, met of zonder afbeelding. Met de API moet je in realtime antwoorden om een aanbieding of een ander abonnement voor te stellen. De aangekondigde module in App Store Connect biedt wel een bericht met een aanbieding, zonder server.

De promotieaanbieding is degene die je in App Store Connect aanmaakt. Volgens de help over promotieaanbiedingen is die bedoeld voor huidige en voormalige abonnees. In een retentiebericht ondertekent jouw server haar, volgens de pagina over het voorbereiden van berichten. Een ander abonnement voorstellen gaat altijd om een abonnement uit dezelfde groep. Ben je nieuw met deze aanbiedingen, lees dan eerst mijn gids over offercodes en promotieaanbiedingen.

Wat je kunt tonen: de exacte limieten

Onderdeel	Limiet van Apple
Titel	Maximaal 66 tekens
Tekst	Maximaal 144 tekens
Opsommingstekens	Maximaal 5
Afbeelding op volle breedte	PNG zonder transparantie, 3840 px breed, 160 tot 2160 px hoog
Afbeelding bij opsomming	1024 × 1024 px
Afbeeldingen per app	Maximaal 2000

De lengtes komen uit de beschrijving van de request body voor het uploaden van een bericht, de formaten uit de pagina over het uploaden van een afbeelding. Apple vraagt ook om afbeeldingen die net zo goed werken in de lichte als in de donkere modus.

Elk bericht en elke afbeelding wordt door Apple beoordeeld. De status gaat van PENDING naar APPROVED, en het systeem toont alleen wat goedgekeurd is. In de sandbox gaat de goedkeuring automatisch. De documentatie stelt een duidelijke inhoudsregel: stuur niets misleidends of onjuists.

De voorwaarden

• Een standaardbericht voor elk product, in elke taal. Zonder dat bericht verschijnt er in die taal niets. Het is ook je reservewiel als je server niet antwoordt.
• Goedgekeurde berichten en afbeeldingen voordat je iets live zet.
• Voor realtime: een snelle server. De pagina over het instellen van het realtime-adres vraagt een geldig SSL-certificaat, TLS 1.2 en een antwoord binnen 700 ms in productie. Duurt het langer, dan mislukt het verzoek en verschijnt het standaardbericht.
• Een geslaagde prestatietest in de sandbox, voordat je je productieadres opgeeft.
• Een controle van de app. Elk verzoek van Apple bevat de identifier van de app, appAppleId. Komt die niet overeen met de jouwe, dan vraagt Apple je niet te antwoorden.

Het realtime-verzoek geeft je de identifier van de oorspronkelijke transactie, het product en de taal van het apparaat. Jij kiest het bericht, volgens je eigen regels.

Retention Messaging instellen: drie routes

Route	Voor wie	Wat je nodig hebt
Module in App Store Connect	Iedereen, zodra hij uit is	Geen code; tekst, afbeelding of aanbieding
API, met je eigen server	Wie een back-end heeft	Toegang van Apple, HTTPS-adres, prestatietest
API, via RevenueCat	Apps die al RevenueCat gebruiken	Toegang van Apple, instellingen in het dashboard

Als er meerdere instellingen naast elkaar bestaan, legt Apple in de WWDC26-sessie de volgorde uit: eerst het realtime-antwoord. Ontbreekt dat of is het verkeerd opgebouwd, dan de instelling uit App Store Connect. Bestaat die niet, dan het standaardbericht dat via de API is ingesteld.

Met je eigen server

1. Vraag toegang aan via het formulier van Apple.
2. Upload je afbeeldingen en daarna je berichten, elk met een titel en een tekst.
3. Wacht op de goedkeuring en stel dan een standaardbericht in voor elk abonnement en elke taal.
4. Voor realtime: maak het endpoint Get Retention Message op je server en geef het op in de sandbox.
5. Start de prestatietest, in de sandbox, met een testtransactie.
6. Is de test geslaagd, geef dan je productieadres op.

Met RevenueCat

Dit is de route die ik heb gekozen: geen server om te schrijven, en mijn apps lopen al via RevenueCat, zoals ik uitleg in RevenueCat en het in-app-abonnement op iOS. Volgens de documentatie van RevenueCat:

1. In het formulier van Apple geef je het adres op dat RevenueCat toont in de instellingen van je App Store-app.
2. Na het akkoord open je Lifecycle, dan Retention, en koppel je het sandbox-adres.
3. Start de prestatietest met een actief sandbox- of TestFlight-abonnement. Die kan tot een uur duren.
4. Maak eerst een standaardbericht, taal voor taal.
5. Voeg daarna realtime-berichten toe, met regels. Een daarvan, "Is in free trial", richt zich op mensen in een gratis proefperiode.
6. Ga naar productie: de sandbox-instellingen worden niet overgenomen, je moet de berichten opnieuw aanmaken.

Een bericht schrijven dat behoudt zonder te misleiden

De tekst ligt vast en wordt door Apple beoordeeld voordat hij verschijnt. Hij kan dus niet over de persoon die hem leest praten, en ook niet over de dag waarop die hem leest. Dit is het standaardbericht dat ik voor TradaZen heb voorbereid (het origineel is in het Frans, hier vertaald):

Titel (50 tekens):
Je wilde leren traden. Ga je nu blind de markt op?

Tekst (117 tekens):
Zonder oefening betaalt je echte geld voor elke fout. Hier kosten ze niets. Je reeks, je league en je lessen stoppen.

De regels die ik mezelf voor mijn vier apps heb opgelegd:

• De titel wijst de persoon op zijn doel, in de vorm van een vraag. Hij laat hem zich niet schamen.
• De tekst zegt precies wat er stopt. Ik schrijf dat de toegang "wordt vergrendeld" als de gegevens blijven, nooit dat ze "verwijderd" worden.
• Geen tijdwoorden zoals "morgen" of "vandaag": dezelfde tekst verschijnt op elk moment van de periode.
• Geen winstbeloftes, geen valse urgentie. Een eerste titel die beloofde dat trading je leven zou veranderen, is vóór het uploaden geschrapt. Guideline 5.6 verbiedt elke manipulatieve praktijk, en de paywall van TradaZen is daarom al eens afgewezen, zoals ik vertel in guideline 5.6 en de paywall.
• Elke taal heeft zijn eigen tekst, met de woorden van de vertaalde app, en tot op het teken nageteld.

Voor TradaZen plan ik ook een realtime-bericht voor mensen in een proefperiode op het jaarabonnement. Dat stelt een goedkoper jaarabonnement uit dezelfde groep voor, omdat mijn cijfers laten zien dat deze mensen de app net zoveel gebruiken als betalende gebruikers: het is de prijs die ze afwijzen. Die instelling wacht op het akkoord van Apple.

Wat je ervan kunt verwachten

Reken niet op een wonder. Apple noemt het aandeel abonnees dat zijn abonnement houdt nadat hij op de bevestigingspagina is beland de save rate. In de WWDC26-sessie meldt Apple dat abonnementen die Retention Messaging gebruiken gemiddeld 1,4 procentpunt op die rate winnen. Berichten met een promotieaanbieding laten de grootste winst zien, 5,5 procentpunt, en de resultaten verschillen per developer. Het onderzoek van RevenueCat ziet op zijn beurt dat abonnees maar zo'n 1,1% van de promotieaanbiedingen en 0,6% van de voorgestelde andere abonnementen accepteren.

Het bericht vervangt dus niet het werk dat eraan voorafgaat. Een gratis proefperiode die binnen een minuut wordt opgezegd, wordt beslist op de paywall en in de eerste sessies: de oorzaken en oplossingen staan in mijn gids over de opgezegde gratis proefperiode, en het opzetten van de proefperiode in de introductieaanbieding.

Je abonnement voorbereiden vóór het bericht

De iOS & Android Kit vertrekt vanuit de startcode van mijn apps: onboarding, paywall en abonnementen zijn al gecodeerd, en het traject in vier stappen brengt je tot in de App Store, in je eigen tempo. De hele keten, van de producten in App Store Connect tot de paywall, staat beschreven op de pagina in-app-abonnement op iOS.

Bereid je je eerste release voor? Doe je gratis diagnose: die vertelt je wat je project echt tegenhoudt en stuurt je mijn checklist tegen afwijzingen door Apple.

Veelgestelde vragen

Wat is de Retention Messaging API van Apple?

Het is een server-to-server-dienst die het bericht kiest dat een abonnee te zien krijgt als hij op Cancel Subscription tikt. Het bericht verschijnt op een bevestigingspagina, vóór de opzegging. Het kan de waarde van het abonnement in herinnering brengen, een ander abonnement of een promotieaanbieding voorstellen.

Is Retention Messaging beschikbaar voor alle developers?

De API is een preview, op aanvraag bij Apple. Op WWDC26 kondigde Apple een module in App Store Connect aan, voor iedereen, gepland voor het najaar van 2026. Op 3 november 2026 beschrijft de help van App Store Connect hem nog niet.

Op welke iOS-versies verschijnt het bericht?

Op iOS 15.1 en iPadOS 15.1 of nieuwer, op visionOS 1 en op macOS 14 of nieuwer. Op een ouder apparaat gaat de opzegging zonder bericht.

Houdt het bericht de abonnee tegen bij het opzeggen?

Nee. De bevestigingspagina houdt een knop om op te zeggen. De abonnee kan ook zijn abonnement houden, of de voorgestelde aanbieding of het andere abonnement accepteren.

Kun je korting aanbieden op het moment van opzeggen?

Ja. Met de API is dat een bericht met een promotieaanbieding, alleen in realtime: de aanbieding wordt in App Store Connect aangemaakt en door jouw server ondertekend. De aangekondigde module in App Store Connect maakt ook een bericht met een aanbieding mogelijk. Een ander abonnement voorstellen gaat altijd om een abonnement uit dezelfde groep.

Hoeveel tekens mag een retentiebericht hebben?

De titel maximaal 66 tekens, de tekst 144. Je kunt tot vijf opsommingstekens toevoegen en een PNG-afbeelding zonder transparantie. Elke taal heeft een eigen standaardbericht nodig.

Heb je een server nodig voor Retention Messaging?

Voor standaardberichten hoef je geen adres te hosten: je roept alleen de API aan om ze te uploaden en in te stellen. Met RevenueCat speelt RevenueCat de rol van server. Realtime vraagt een HTTPS-adres dat binnen 700 ms antwoordt. De aangekondigde module in App Store Connect stel je zonder code in.