Migrer des abonnements vers Stripe Billing à l'aide du kit d'outils

Comment migrer vos abonnements existants vers Stripe à l'aide du kit d'outils.

Utilisez le kit d’outils de migration Billing dans le Dashboard Stripe pour migrer vos abonnements existants depuis un système tiers, un système interne ou un compte Stripe existant vers Stripe Billing.

Avant de commencer

Si vous ne l’avez pas encore fait, passez en revue les étapes de la migration.
Créez une intégration Stripe Billing avant de commencer la migration. Il s’agit d’une configuration ponctuelle que vous n’avez pas besoin de répéter pour les prochaines migrations.
Demandez l’importation de données du PAN à votre prestataire de services de paiement actuel. Cette étape n’est requise que si vous migrez vers Stripe à partir d’un autre prestataire. Si vous migrez de Stripe vers Stripe, vous pouvez ignorer ce prérequis.
Si vous effectuez une migration à partir d’un système tiers ou maison, ponctuez soigneusement l’annulation de vos abonnements existants et la création de nouveaux abonnements dans Stripe. Pour éviter de manquer une période de facturation, créez les nouveaux abonnements dans Stripe avant d’annuler les anciens abonnements. Pour éviter la double facturation, annulez les abonnements dans votre ancien système avant que les abonnements ne soient paramétrés pour être facturés. Pour les abonnements dont les dates de facturation sont proches de la migration, planifiez-les pour qu’ils démarrent après le cycle afin que la facture finale soit dans l’ancien système.

Ouvrir le kit d'outils de migration Billing

Créez un environnement de test dans le Dashboard si vous souhaitez d’abord effectuer un test de migration.

Accédez au Dashboard > Abonnements > Migrations.
Vous pouvez également cliquer sur le menu déroulant) à côté de + Créer un abonnement, et sélectionner Migrer les abonnements.
Pour démarrer votre migration, cliquez sur Commençons.

Télécharger un fichier CSV

Exportez tout d’abord vos abonnements existants en faisant correspondre les données exportées à un fichier CSV compatible avec la migration. Vous pouvez créer votre propre fichier CSV ou télécharger l’un des modèles de CSV suivants fournis par Stripe (Basique, Articles à prix multiples et Tarifs ad hoc). Vous trouverez également des exemples de fichiers CSV pour les cas d’usage de migration les plus courants.

Cliquez sur Télécharger le modèle au format CSV.
Choisissez un modèle CSV (basique, articles à prix multiples ou tarifs ad hoc) en fonction de votre cas d’usage en matière de facturation.
CSV basique
Cet exemple montre une migration d’abonnements pour des cas d’usage courants, notamment la migration des quantités, taxes, dates de début du cycle de facturation, réductions, périodes d’essai ou antidatages.
Spécifier les champs suivants pour un fichier CSV basique :
Fichier CSV d’articles à prix multiples
Cet exemple illustre une migration comportant plusieurs produits par abonnement.
Spécifier les champs suivants pour un fichier CSV d'articles à prix multiples :
Tarifs ad hoc CSV
Cet exemple illustre la gestion d’une migration d’abonnement à l’aide de tarifs ad hoc pour des produits existants.
Spécifier les champs suivants pour un fichier CSV de tarifs ad hoc :
Dans le fichier CSV, indiquez les informations des abonnements que vous souhaitez exporter.
Pour les migrations Stripe vers Stripe
Si vous effectuez des migrations d’abonnements entre des comptes Stripe, reportez-vous au fichier CSV exemple avant de spécifier et de télécharger un fichier CSV.

Charger un fichier CSV

Cliquez sur Charger un fichier CSV. La taille limite des fichiers CSV est de 120 Mo.

Stripe valide le fichier pour vérifier que les abonnements chargés sont au format CSV requis. Ce processus peut prendre quelques heures, selon la taille du fichier. Si le fichier est valide, vous pouvez passer à l’étape suivante de la migration. En cas d’erreurs de validation, vous devez les résoudre pour continuer.

Vérifier les abonnements chargés

Une fois que Stripe a validé votre fichier CSV, vérifiez le récapitulatif des abonnements chargés afin de détecter d’éventuelles incohérences :

Faites une vérification croisée pour déterminer si les éléments suivants sont corrects :
- Date de chargement
- Nom du fichier chargé
- Nombre d’abonnements
- Nombre de clients
- Date de mise en service du premier abonnement
Si tout est valide, cliquez sur Démarrer la migration.
Si vous voyez des erreurs, cliquez sur Annuler la migration et recommencez la migration à partir de Télécharger un fichier CSV.

Suivre la progression de la migration

Après avoir examiné vos abonnements téléchargés, suivez la progression de votre migration :

Progression de la migration	Description
Migration en cours	Vos abonnements sont mis en file d’attente pour être planifiés à la date de début spécifiée. Ce processus peut prendre de quelques minutes à quelques heures selon la taille du fichier. Par exemple, la validation et la migration de 100 000 abonnements prennent environ 30 minutes. La boîte à outils de migration de Billing utilise la planification d’abonnement pour migrer vos abonnements. Vos abonnements peuvent ainsi rester à l’état planifié pendant 24 heures avant la mise en production. Dans un environnement de test, ce délai est réduit à 1 heure pour une évaluation et des tests plus rapides.
Abonnements planifiés	Après la migration, vos abonnements restent dans un état planifié pendant 24 heures avant la mise en production. Vous disposez de 10 heures pour annuler ces planifications d’abonnements via le kit d’outils. Vous ne pouvez pas modifier les abonnements planifiés à l’aide du kit d’outils de migration. Pour modifier des abonnements planifiés, vous pouvez appeler l’endpoint de mise à jour ou modifier chaque abonnement individuellement sur la page Abonnements du Dashboard. Les clients ne peuvent pas annuler les abonnements planifiés via leur portail client. Ils ne peuvent annuler que les abonnements en cours.
Mettre vos abonnements en production	Après 24 heures, vos abonnements planifiés sont mis en production et débitent les clients conformément aux dates de début applicables. Vous pouvez consulter tous vos abonnements réels sur la page Abonnements du Dashboard. Une fois la migration mise en production, nous vous recommandons de surveiller vos abonnements à partir du premier paiement. Assurez-vous que les dates et montants des paiements correspondant aux abonnements migrés correspondent aux valeurs start_date spécifiées. Les clients peuvent annuler les abonnements en temps réel via leur portail client.
Surveiller les abonnements	Une fois la migration lancée en production, surveillez vos abonnements pour détecter d’éventuels problèmes liés aux moyens de paiement. Par exemple, vérifiez que les transactions ne comportent pas de codes de refus de paiement irrécupérables reçus de l’émetteur, tels que `incorrect_number`, et prenez des mesures pour vous assurer que les factures sont payées. Envisagez de notifier les clients dont le moyen de paiement n’est pas valide par d’autres canaux que l’e-mail, par exemple par SMS ou via des notifications dans l’application. Lorsque vous utilisez le recouvrement automatique, vérifiez les factures en cours ou en retard pour vous assurer que les clients disposent bien de moyens de paiement par défaut, sans lequel le recouvrement de la facture ne pourrait avoir lieu.

Afficher toutes les migrations

Pour afficher toutes vos migrations :

Sélectionnez la migration que vous souhaitez examiner dans Migrations.
Pour ouvrir une migration, cliquez sur Afficher dans le menu déroulant.
Vous pouvez suivre les champs suivants :
- Date de chargement
- Nom du fichier
- ID de migration Stripe Billing
- Nombre d’abonnements
- État de la migration

FacultatifAnnuler une migration

Si vous repérez des problèmes liés aux abonnements planifiés, vous pouvez annuler la migration et revenir en arrière sur les abonnements planifiés. Le Dashboard affiche un horodatage pour indiquer si vous pouvez encore annuler la migration à l’aide du kit d’outils. Vous disposez de 10 heures à compter de la planification des abonnements pour les annuler. Après 10 heures, l’option d’annulation est désactivée dans le kit d’outils. Pour annuler la migration après 10 heures, vous pouvez appeler l’endpoint d’annulation ou annuler individuellement chaque abonnement sur la page Abonnements du Dashboard.

Recherchez la migration que vous souhaitez annuler dans vos Migrations.
Cliquez sur Annuler la migration dans le menu déroulant.

FacultatifExécuter plusieurs migrations

Vous pouvez exécuter autant de migrations d’abonnements simultanées que vous le souhaitez. Pour les migrations importantes, divisez les abonnements en lots et commencez par un petit lot. Cela vous permettra d’identifier rapidement les problèmes de validation et de gagner du temps.

Pour démarrer une nouvelle migration :

Cliquez sur Démarrer une nouvelle migration.
Recommencez le processus de migration à partir du téléchargement de fichier CSV.

Vous trouverez également des exemples de fichiers CSV pour les cas d’usage de migration les plus courants.

FacultatifRésoudre les erreurs de validation

Cas d’usage de migration

Vous pouvez appliquer les cas d’usage de migration contenus dans cette section à votre propre migration, le cas échéant. Dans ces exemples, les horodatages sont au format Unix EPOCH. Les exemples incluent également des ID de client et de tarif de test que vous pouvez utiliser dans un environnement de test.

Vous pouvez combiner n’importe quel modèle de fichier CSV fourni par Stripe (Basique, Articles à prix multiples, Tarifs ad hoc) avec n’importe lequel de ces exemples selon vos besoins.

Migrer des abonnements avec différents modèles tarifaires

Migrer des abonnements avec différentes méthodes d’encaissement des paiements

Migrer des abonnements à différents stades du cycle d’abonnement

Migrer des abonnements avec taxes

Migrer des abonnements avec des réductions

Migrer des abonnements entre comptes Stripe

Migrer des abonnements à plusieurs phases

Référence pour le fichier CSV

Le kit d’outils de migration nécessite que vous chargiez un fichier CSV contenant des informations spécifiques dans les champs voulus.

Prérequis CSV

Avant de créer ou de télécharger un fichier CSV, assurez-vous de disposer d’un accès aux informations suivantes :

Objet Customer	Tous les clients doivent disposer d’un moyen de paiement par défaut. En l’absence de moyen de paiement par défaut, les futurs paiements d’abonnement échoueront. Si aucun moyen de paiement par défaut n’est défini pour vos clients après la migration de leurs données, deux options s’offrent à vous : Obtenez le consentement de l’utilisateur ou basez-vous sur son comportement de paiement antérieur pour déterminer le moyen de paiement par défaut de chaque client. Utiliser ce script pour associer le moyen de paiement le plus récent à vos clients et le définir comme moyen de paiement par défaut.
Calcul automatique des taxes	Si vous utilisez Stripe Tax (et y avez défini le calcul automatique des taxes sur true), tous les clients doivent avoir une adresse ou un code postal (ou les deux) par pays. Stripe a besoin de ces informations pour calculer les taxes à appliquer aux abonnements.
collection_method	Si vous utilisez le moyen de paiement `send_invoice` pour vos abonnements : Ajoutez les adresses e-mail des clients concernés. Ajoutez le paramètre days_until_due dans le fichier CSV de migration pour indiquer la validité des factures de chaque client.
Dates	Pour garantir une synchronisation précise, accordez une attention particulière aux fuseaux horaires lorsque vous créez des formats de date et d’heure epoch pour votre fichier CSV de migration. Pour le kit d’outils, définissez la start_date avec une marge d’au moins 24 heures par rapport à la date de chargement du fichier CSV. Nous créons une planification d’abonnement afin que vous disposiez de ce délai pour confirmer et vérifier l’exactitude des données. Lorsque la date de début arrive, l’abonnement passe de l’état planifié à l’état actif.
Bons de réduction	Si le début du cycle de facturation de la planification d’abonnement ou de l’abonnement se situe dans le futur et que l’attribut `proration_behavior` est défini sur `none`, la modification de ces objets annule le bon de réduction. Réappliquez le bon de réduction si vous mettez à jour la planification d’abonnement ou l’abonnement. Pour migrer un abonnement avec un `discount_behavior` en cours : Définissez une phase future qui supprime le bon de réduction à la date souhaitée au lieu d’attendre qu’il expire. Créez un coupon d’une durée différente pour chaque abonnement, afin qu’ils expirent tous sans problème.
Migration interne à Stripe	Les utilisateurs peuvent migrer des abonnements entre des comptes Stripe. Vous devez renseigner les ID des client et des tarifs (ainsi que les ID des bons de réduction et les numéros fiscaux si vous les utilisez) dans le modèle associé à votre compte Stripe de destination, et non à votre compte Stripe source. L’outil de migration génère une erreur si vous renseignez des ID associés à votre compte source.

Spécification CSV complète

Attribut	Type	Description
`customer` (obligatoire)	ID client Stripe	Identifiant du client pour lequel l’abonnement doit être créé.
`start_date` (obligatoire)	Horodatage au format epoch UNIX	Détermine le moment de la création de l’abonnement. Vous devez fournir une valeur de 24 heures (ou plus) dans le futur. Dans un environnement de test, vous pouvez définir cette valeur sur 1 heure dans le futur.
`price` (obligatoire)	ID de tarif Stripe	Doit être un tarif récurrent. Si vous migrez plusieurs articles, utilisez plutôt le format `items.x.{price, quantity}`. Les tarifs ad hoc sont également pris en charge avec `adhoc_items.x.{amount, interval, product, currency}`.
`quantity`	Nombre	Détermine la quantité d’un abonnement. Par défaut, chaque abonnement concerne un produit, mais Stripe vous permet d’abonner un client à plusieurs quantités d’un article.
`items.x.price` (obligatoire)	ID de tarif Stripe	L’ID de l’objet Price. Doit être un tarif récurrent.
`items.x.quantity`	Nombre	Détermine la quantité d’un abonnement. Par défaut, chaque abonnement concerne un produit, mais Stripe vous permet d’abonner un client à plusieurs quantités d’un article.
`adhoc_items.x.amount` (obligatoire)	Nombre entier	Nombre entier positif exprimé en centimes (ou zéro pour un tarif gratuit). Veuillez consulter la page Créer un abonnement pour en savoir plus.
`adhoc_items.x.product` (obligatoire)	ID de produit Stripe	Identifiant du produit qui correspond au tarif ad hoc.
`adhoc_items.x.interval` (obligatoire)	`day`, `week`, `month` ou `year`	Fréquence de facturation.
`adhoc_items.x.currency` (obligatoire)	Chaîne	Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge.
`adhoc_items.x.quantity`	Nombre	Détermine la quantité d’un abonnement. Par défaut, chaque abonnement concerne un produit, mais Stripe vous permet d’abonner un client à plusieurs quantités d’un article.
`metadata_source`	Chaîne	Si vous effectuez une migration Stripe vers Stripe, saisissez `internal:Stripe`.
`metadata_*`	Chaîne	Associe ces paires clé-valeur à un objet. Cela est utile pour stocker des informations supplémentaires sur l’objet dans un format structuré.
`automatic_tax`	Booléen	Indiquez `true` pour utiliser les paramètres fiscaux automatiques de Stripe Tax.
`coupon`	ID de bon de réduction Stripe	Identifiant du bon de réduction à appliquer à cet abonnement.
`currency`	Chaîne	Code de devise ISO à trois lettres en minuscules. Il doit s’agir d’une devise prise en charge. Utilisé pour la sélection des devises dans le cas de tarifs multidevises.
`trial_end`	Timestamp	Définit la phase de la période d’essai entre la date de début et la date de `trial_end`. Vous devez spécifier une valeur antérieure à la date de fin du cycle/de la phase et vous ne pouvez pas la combiner avec la période d’essai.
`proration_behavior`	`create_prorations` ou `none`	Détermine si l’abonnement crée des calculs au prorata après la migration. La valeur par défaut est `create_prorations`.
`collection_method`	`charge_automatically` ou `send_invoice`	Lors du paiement automatique, Stripe tente de payer l’abonnement sous-jacent à la fin de chaque cycle de facturation en utilisant la source par défaut attachée au client. La valeur par défaut est `charge_automatically`. Lors de l’envoi d’une facture, Stripe envoie une facture avec les instructions de paiement par e-mail à votre client et marque l’abonnement comme actif. Si vous utilisez `send_invoice`, vous devez définir `days_until_due`.
`default_tax_rate`	ID Stripe Tax	Définit les `default_tax_rates` par défaut de l’abonnement. Cela détermine également les taux `default_tax_rates` de la facture pour toutes les factures émises par l’abonnement au cours de cette phase. Cette valeur est incompatible avec `automatic_tax`.
`backdate_start_date`	Horodatage au format epoch UNIX	Détermine la `start_date` de l’abonnement créé, qui doit se situer dans le passé. Si cette option est activée, vous devez définir `proration_behavior` sur la valeur `none`. Cela empêche la création d’une facture au prorata pour la période comprise entre la date `backdate_start_date` et la date `start_date` réelle. Pour en savoir plus, veuillez consulter la section antidater sans facturer les utilisateurs.
`billing_cycle_anchor`	Timestamp	Détermine les dates futures de facturation de l’abonnement du client.
`days_until_due`	Nombre entier	Nombre de jours entre la création de la facture et son échéance. Cette information est obligatoire et n’est valable que pour les factures dont `collection_method` est définie sur `send_invoice`.
`cancel_at_period_end`	Booléen	Indique la valeur `true` pour annuler un abonnement à la fin de la période.

Voir aussi

Migrer des abonnements à l’aide des API Stripe