Ajouter un parcours d’annulation à Paddle Billing

Un parcours d’annulation est la courte étape entre « je veux résilier » et la résiliation elle-même : demander pourquoi, proposer quelque chose qui correspond à la raison, et résilier proprement si le client veut toujours partir. Ce guide explique comment fonctionne la résiliation dans Paddle Billing, ce que Paddle propose déjà nativement, et comment construire votre propre étape de rétention sur son API.

Il s’en tient à la documentation développeur de Paddle : annuler un abonnement, mettre en pause un abonnement, reprendre un abonnement, modifier un abonnement, les remises, le provisioning et les webhooks, le portail client et Cancellation Flows (tous consultés en novembre 2026). Il porte sur Paddle Billing, pas sur Paddle Classic, dont l’API est différente.

Paddle est le marchand officiel

Une chose à garder en tête tout du long : Paddle est le merchant of record (marchand officiel) de vos ventes. Il vend à votre client, gère la fiscalité et, selon Paddle, gère le support de facturation et les chargebacks. La relation de paiement est donc entre le client et Paddle. Votre parcours d’annulation ne doit modifier les abonnements que via l’API de Paddle ou ses propres outils, jamais en essayant d’arrêter les paiements autrement.

Comment fonctionne la résiliation dans Paddle Billing

Paddle vous offre trois endroits où un abonnement peut être résilié.

1. L’API d’annulation

Vous résiliez avec POST /subscriptions/{subscription_id}/cancel. Le champ effective_from décide du moment :

`effective_from`	Ce qui se passe
`next_billing_period` (par défaut, et c’est aussi l’effet d’un corps vide)	Paddle ajoute un `scheduled_change` avec l’action cancel. L’abonnement reste actif jusqu’à sa prochaine date de facturation, et `next_billed_at` devient null
`immediately`	Le statut passe à `canceled` tout de suite et `subscription.canceled` est envoyé

Paddle documente quelques limites sur la page d’annulation :

Vous ne pouvez pas résilier ni mettre en pause dans les 30 minutes qui précèdent la prochaine date de facturation.
Une résiliation planifiée peut être retirée en modifiant l’abonnement avec scheduled_change à null. C’est ainsi qu’on « annule » une résiliation avant qu’elle prenne effet.
Un abonnement annulé ne peut pas être rétabli. Un client qui revient a besoin d’un nouvel abonnement, ce qui compte pour la reconquête.
Un abonnement en pause ne peut être résilié qu’avec effective_from: immediately.

2. Le portail client

Le portail client de Paddle permet aux clients de résilier et de mettre à jour leurs informations de paiement. La documentation de Paddle indique que la pause n’est pas prise en charge dans le portail : une offre de pause doit donc venir de votre app ou des Cancellation Flows de Paddle.

3. Les Cancellation Flows de Paddle

Paddle a une fonctionnalité native pour exactement cela, qui fait partie de Paddle Retain. Vous la configurez dans Retain › Cancellation Flows (guide de configuration). Elle demande une raison de résiliation et peut proposer une pause, un changement d’offre, un contact avec le support ou une remise limitée dans le temps. Selon le changelog de janvier 2026 de Paddle, une fois un parcours configuré, il se lance automatiquement quand les clients résilient dans le portail client ou via les liens de résiliation des emails d’abonnement de Paddle. Dans votre propre app, vous le lancez avec Paddle.Retain.initCancellationFlow(), qui renvoie un statut comme retained, aborted ou chose_to_cancel. Un changelog de septembre 2026 ajoute les tests en sandbox via le portail client, tandis que les parcours lancés avec initCancellationFlow() ne tournent toujours que sur les comptes live.

Soyons clairs : si vous n’avez besoin que d’un questionnaire sur la raison et d’une offre standard dans Paddle, cette fonctionnalité native peut suffire, et Paddle l’indique sans surcoût pour les clients Paddle Billing. La suite de ce guide s’adresse à ceux qui veulent leur propre parcours, leur propre design, ou des offres qui dépendent de données que Paddle n’a pas.

Les offres de rétention que l’API de Paddle permet

Pause

POST /subscriptions/{subscription_id}/pause met un abonnement en pause (guide). Il prend effective_from (next_billing_period ou immediately) et une date resume_at facultative. Une pause à la prochaine période de facturation crée un changement planifié ; le statut devient paused quand il prend effet.

Pour faire revenir un client plus tôt, POST /subscriptions/{subscription_id}/resume ne fonctionne que sur les abonnements en pause. Le champ on_resume décide de la facturation : par défaut, Paddle démarre une nouvelle période de facturation et prélève immédiatement ; continue_existing_billing_period garde l’ancienne période. Paddle annule aussi les transactions de renouvellement impayées quand un abonnement est mis en pause, pour éviter de facturer deux fois des périodes qui se chevauchent.

Remise

Créez la remise une fois avec POST /discounts. Pour une offre de rétention comme « -50 % pendant 3 mois », mettez recur à true et maximum_recurring_intervals au nombre de périodes de facturation. Appliquez-la ensuite à l’abonnement avec PATCH /subscriptions/{subscription_id}, en passant un objet discount avec l’ID de la remise et un effective_from à next_billing_period ou immediately (modifier un abonnement). Envoyer discount: null la retire. Paddle précise que les renouvellements et les changements en cours de cycle ne comptent pas comme de nouvelles utilisations.

Changement d’offre

Un passage à une offre inférieure est aussi une modification d’abonnement : remplacez les items par le prix moins cher. Quand vous changez les items ou la date de facturation, Paddle exige proration_billing_mode. Utilisez l’endpoint de prévisualisation pour montrer au client ce qu’il paiera avant de confirmer.

Construire votre propre parcours d’annulation sur Paddle

Placez le point d’entrée de la résiliation dans votre app. Faites pointer « Résilier l’abonnement » vers votre parcours, pas directement vers l’appel API. Laissez aussi le portail client accessible ; c’est le chemin de Paddle, et des clients peuvent l’utiliser.
Posez une question : pourquoi. Utilisez une courte liste de raisons plus « Autre » avec un champ libre. Stockez la réponse avec l’ID de l’abonnement.
Montrez une offre qui correspond à la raison. « Trop cher » appelle une remise ou une offre moins chère. « Je ne m’en sers pas en ce moment » appelle une pause avec une date resume_at. « Il manque une fonctionnalité » ou « Trop complexe » appelle un échange avec le support. N’empilez pas les offres.
Gardez « Résilier maintenant » visible à chaque étape. Le client doit pouvoir terminer la résiliation à tout moment sans accepter d’offre. C’est une question de confiance et, à plusieurs endroits, de loi.
Appelez Paddle pour le résultat. Remise : PATCH de l’abonnement avec la remise. Pause : POST .../pause. Changement d’offre : PATCH des items après une prévisualisation. Résiliation : POST .../cancel avec effective_from: next_billing_period, pour que le client garde ce qu’il a payé.
Confirmez la suite. Indiquez au client la date de fin d’accès ou de fin de pause. Lisez-la dans l’abonnement renvoyé par Paddle plutôt que de la calculer vous-même.
Laissez-le changer d’avis. Tant que la résiliation planifiée n’a pas pris effet, un bouton « Garder mon abonnement » peut vider scheduled_change.

Les webhooks à écouter

Le guide de provisioning de Paddle recommande subscription.created et subscription.updated comme événements de base, car subscription.updated couvre les renouvellements, changements d’offre, pauses, reprises et résiliations. Quelques événements dédiés sont utiles comme signaux clairs :

Événement	Quand il est envoyé
`subscription.updated`	Tout changement, y compris la planification d’une résiliation
`subscription.canceled`	Le statut devient `canceled` : immédiatement, ou à la date de facturation pour une résiliation planifiée
`subscription.past_due`	L’abonnement passe en impayé après un renouvellement échoué

Les pauses et reprises passent aussi par subscription.updated, avec un statut qui passe à paused ou en sort ; consultez la référence des webhooks de Paddle pour les événements dédiés disponibles dans votre version d’API.

Deux détails de la documentation de Paddle : pour une résiliation planifiée, gardez l’accès jusqu’à la date d’effet du changement planifié ; et dédoublonnez sur event_id en comparant occurred_at, car les événements peuvent arriver dans le désordre. Le payload de subscription.canceled ne contient pas management_urls.

Après la résiliation : la reconquête

Comme Paddle ne peut pas rétablir un abonnement annulé, une offre de reconquête doit mener à un nouveau checkout. Gardez la raison de résiliation que vous avez recueillie, attendez un délai raisonnable, et envoyez une offre qui répond à cette raison : une nouvelle fonctionnalité pour « fonctionnalités manquantes », un prix plus bas pour « trop cher ». Envoyez le client vers un checkout où la remise est déjà appliquée.

Le faire avec NoChurn

NoChurn lit vos abonnements et événements Paddle et ajoute un parcours d’annulation avec raisons, offres (remise, pause, changement d’offre) et un bouton d’annulation en un clic qui reste visible à chaque étape, hébergé ou headless via l’API. Les offres acceptées et les résiliations sont appliquées dans Paddle, et Paddle reste le marchand officiel : il garde le checkout, les paiements, la récupération des paiements, la fiscalité et le portail client. Les litiges sont gérés par Paddle et affichés en lecture seule dans NoChurn. NoChurn envoie aussi des emails de reconquête à J30, J60 et J90 selon la raison de la résiliation, et il est gratuit jusqu’à 300 $ de MRR. Voir NoChurn + Paddle.