Migrer un système de billing se situe au croisement d'une importance critique et d'un risque significatif. Une erreur peut conduire à des doublons de facturation, à des records d'abonnement perdus, ou à un reporting de revenus cassé - autant de raisons qui maintiennent les équipes finance sur le qui-vive et obligent les ingénieurs à vérifier des feuilles de calcul à des heures indues.
Le Migration toolkit de Stripe Billing apporte une solution no-code, pilotée depuis le dashboard. Plutôt que d'écrire des scripts ou de l'outillage API maison, l'équipe charge un CSV contenant les abonnements existants pour les recréer dans Stripe en miroir de leur configuration actuelle.
Quelques détails d'implémentation requièrent toutefois une attention particulière pour éviter une double facturation accidentelle.
Prérequis : les clients et les prix doivent déjà exister
Avant de migrer les abonnements, les clients doivent déjà exister dans Stripe avec un moyen de paiement valide attaché. Le Migration toolkit crée des abonnements uniquement, pas les records clients.
Cela passe en général par deux chemins :
- Clients Stripe existants : les équipes qui utilisent déjà Stripe pour les paiements, mais pas pour les abonnements, ont probablement déjà leurs clients en place.
- Import des données PAN : Stripe peut importer des tokens de moyens de paiement depuis les processeurs précédents, via un processus séparé à initier en amont.
Chaque ligne du CSV référence un identifiant client qui doit déjà exister ; les IDs manquants provoquent des erreurs de validation. De même, les products et prices doivent être définis au préalable.
Pour démarrer : aller dans Subscriptions, sélectionner l'onglet Migrations, puis cliquer sur « + Start new migration ».
Le format CSV
Après avoir initié une nouvelle migration, un assistant vous demande des détails sur le type de migration. Stripe fournit des CSV templates pour les scénarios courants :
- Basic : abonnements standard avec quantité, taxes, remises, périodes d'essai
- Multi-price items : abonnements incluant plusieurs produits
- Ad-hoc pricing : tarification personnalisée appliquée à des produits existants
Les champs les plus critiques sont :
| Champ | Obligatoire | Description |
|---|---|---|
customer | Oui | L'ID du client Stripe (doit déjà exister) |
price ou items.0.price | Oui | L'ID du price Stripe pour l'abonnement |
start_date | Oui | Date d'activation de l'abonnement dans Stripe |
backdate_start_date | Non | Pour antidater l'historique d'abonnement |
proration_behavior | Non | Contrôle si des frais au prorata sont créés |
billing_cycle_anchor | Non | Détermine la prochaine date de facturation |
La plupart des complications de migration viennent de la façon dont ces champs interagissent, en particulier les champs de date et le proration.
Une exigence de timing critique
Le champ start_date détermine quand les abonnements s'activent dans Stripe. Stripe impose un délai minimum entre l'upload et l'activation :
- Live mode : environ 24 heures
- Test mode : généralement plus court, autour d'une heure
Cette fenêtre fournit une marge de sécurité. Entre l'upload et l'activation, on peut revoir les abonnements importés dans le dashboard. Vérifier que les prix, quantités et affectations clients sont corrects. En cas de problème, on peut annuler toute la migration avant que les facturations ne s'enclenchent.
Mettre start_date assez loin dans le futur donne plus de temps de revue. Le mettre pour activer immédiatement laisse peu de marge si un problème survient. Il y a rarement une bonne raison d'accélérer ce processus, donc accordez-vous des fenêtres de revue suffisantes.
Validation, puis revue
À l'upload du CSV, Stripe valide l'intégralité du fichier avant de créer le moindre abonnement. Cette étape attrape les champs manquants ou mal formés, les IDs clients ou prices invalides, les start dates trop proches, et les combinaisons de champs invalides.
Stripe affiche toutes les erreurs de validation simultanément, plutôt que d'échouer ligne par ligne, ce qui permet une correction en une seule passe. En cas d'erreurs, Stripe fournit un CSV téléchargeable expliquant ligne par ligne les défaillances de chaque entrée.
Après correction, on remet à jour le CSV dans la même migration. Petite subtilité d'UI : cliquer sur « Start again » remonte le CSV dans la tentative de migration en cours, alors que « Fix errors » suggère de créer une nouvelle migration. En général, « Start again » garde un historique de migration plus propre, regroupé sous une seule tentative.
Une fois la validation réussie, les abonnements sont créés en état scheduled - ils existent dans Stripe mais ne sont pas encore actifs. Le temps de validation dépend du nombre de records ; les migrations de test de moins de 100 abonnements valident généralement instantanément.
Après validation réussie, un bouton « View subscription schedules » apparaît, qui mène vers la liste des subscription schedules. Avant que les schedules ne s'activent, revoir les abonnements dans le dashboard. Annuler ceux qui ne semblent pas corrects, individuellement ou par lots si la start date est suffisamment lointaine.
Antidater : la source de confusion la plus courante
Si un client s'est abonné initialement en janvier 2023 et que la migration a lieu en 2026, il est probablement souhaitable de refléter cet historique dans Stripe. C'est là qu'intervient backdate_start_date - et c'est le champ le plus susceptible de créer de la confusion, surtout en regard de start_date.
La distinction critique :
start_date- quand l'abonnement devient actif dans Stripe et que la facturation démarre. Doit être dans le futur.backdate_start_date- la date historique enregistrée comme début initial de l'abonnement. Peut être dans le passé.
customer,items.0.price,start_date,backdate_start_date
cus_ABC123,price_XYZ789,1705753518,1658179441L'abonnement s'active le 15 février 2026, mais Stripe enregistre le client comme abonné depuis janvier 2023. Cela impacte le reporting, les analytics et la visibilité dans le dashboard du client.
Ne pas mettre start_date à une date passée - Stripe le rejette en validation.
Le proration : la zone à risque
C'est là que les migrations échouent le plus souvent, avec à la clé des facturations clients inattendues.
Par défaut, le proration_behavior de Stripe est réglé sur create_prorations. Si Stripe identifie un décalage entre le billing cycle anchor et la start date, il génère des factures au prorata. En migration, cela revient typiquement à refacturer aux clients des périodes qu'ils ont déjà payées ailleurs.
Dans la quasi-totalité des scénarios de migration, désactivez explicitement cela :
customer,items.0.price,start_date,backdate_start_date,proration_behavior
cus_ABC123,price_XYZ789,1705753518,1658179441,noneMettre proration_behavior à none signifie : « ce client a déjà payé jusqu'à sa prochaine date de facturation ; reprenez simplement la facturation normale à partir de là ». Si vous ne devez retenir qu'une chose de cet article, retenez ce principe.
Les billing cycle anchors : pourquoi ils comptent
Le billing_cycle_anchor détermine quand les futures factures sont générées. Un mauvais alignement avec les dates de facturation existantes peut amener Stripe à « corriger » le cycle, ce qui déclenche des prorations ou des premières factures déroutantes.
En migration, l'objectif est typiquement de reproduire fidèlement la cadence de facturation existante, pour qu'aucun client ne perçoive un changement après la migration.
Par exemple, pour un abonnement où le client s'est inscrit le 1er janvier 2026 et doit être facturé le 1er de chaque mois, mais où la migration a lieu le 10 février :
| Champ | Détail |
|---|---|
start_date | timestamp du 10 février |
backdate_start_date | timestamp du 1er janvier 2026 |
billing_cycle_anchor | timestamp du 1er mars 2026 |
proration_behavior | none |
En inspectant ce schedule dans le dashboard, on voit la première phase démarrer le 10 février, avec la prochaine facturation au 1er mars - ce qui évite la double facturation.
Un workflow de migration typique
- Exporter depuis le système actuel : références clients, dates de début initiales, plans, quantités.
- Garantir la présence des clients dans Stripe : soit déjà existants, soit via un import PAN.
- Mapper les données soigneusement : faire correspondre les clients aux IDs Stripe et les plans aux IDs de price.
- Définir les dates avec soin :
start_dateavec une marge confortable,backdate_start_datereflétant le début initial de l'abonnement,billing_cycle_anchoraligné sur la facturation existante. - Désactiver le proration : mettre
proration_behaviorànonesauf si vous voulez explicitement créer des charges. - Uploader et valider : résoudre toutes les erreurs avant d'aller plus loin.
- Revoir dans le dashboard : faire des contrôles ponctuels sur les abonnements pendant qu'ils sont encore en scheduled.
- Surveiller l'activation : observer le premier cycle de facturation pour détecter les échecs ou les factures inattendues.
Erreurs courantes à éviter
- Mettre
start_datetrop tôt : donnez-vous de la marge. Il n'y a aucun gain à précipiter ce processus. - Oublier de désactiver le proration : à elle seule, cette omission cause la plupart des facturations accidentelles.
- Confondre
start_dateetbackdate_start_date: l'un porte sur le timing de la facturation, l'autre sur les records historiques. - Moyens de paiement manquants : les abonnements peuvent exister sans, mais le traitement des factures échouera.
- Fautes de frappe dans les IDs de price : même une erreur d'un caractère provoque l'échec d'une ligne.
Le Migration toolkit, ça vaut le coup ?
Pour très peu d'abonnements - quelques dizaines au maximum - une création manuelle ou par appel API peut être tout aussi efficace.
Pour des volumes plus importants, le Migration toolkit fait gagner un temps considérable. Fender a notamment « migré 70 000 abonnés en quelques heures » avec cette solution. À elle seule, la phase de validation amont, qui identifie l'ensemble des problèmes plutôt que de les découvrir au compte-gouttes via des appels API individuels, justifie l'investissement d'apprentissage.
Le succès dépend d'une bonne compréhension des champs critiques - start_date, backdate_start_date, billing_cycle_anchor et proration_behavior - et d'une bonne utilisation de la fenêtre de revue. Bien exécutée, la migration des abonnements se fait sereinement, sans surprise pour les clients ni pour les équipes finance.
