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 > Souscriptions > 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 :

Attribut	Type	Exemple	Description
`customer` (obligatoire)	ID client Stripe	`cus_xxx1`	Identifiant du client pour lequel l’abonnement doit être créé.
`start_date` (obligatoire)	Horodatage au format epoch UNIX	`1658179441`	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	`price_1LDGNmDK0D4Fox2RxIaXQkBp`	Vous devez utiliser 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, product, interval,currency}`.
`quantity`	Nombre	`1`	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.*`	Chaîne	`subscription_1`	Associe ces paires clé-valeur que l’on peut associer à un objet. Cela est utile pour stocker des informations supplémentaires sur l’objet dans un format structuré. Vous pouvez ajouter tous les champs de métadonnées que vous souhaiter (par exemple `metadata_third_party_sub_id`). S’il s’agit d’une migration de Stripe vers Stripe, entrez `internal:Stripe`.
`automatic_tax`	Booléen	`false`	Indiquez `true` pour utiliser les paramètres fiscaux automatiques de Stripe Tax.
`billing_cycle_anchor`	Horodatage au format epoch UNIX	`1658179441`	Détermine la prochaine date de facturation de l’abonnement du client.
`coupon`	ID de bon de réduction Stripe	`50_off`	Identifiant du bon de réduction à appliquer à cet abonnement.
`trial_end`	Horodatage au format epoch UNIX	`1658179441`	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 et vous ne pouvez pas la combiner avec la période d’essai.
`proration_behavior`	Énumération	`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`	Énumération	`charge_automatically` ou `send_invoice`	Lors d’un débit automatique, Stripe tente de payer l’abonnement sous-jacent à la fin de chaque période de facturation en utilisant la source par défaut associée au client. Lors de l’envoi d’une facture, Stripe envoie à votre client une facture par e-mail avec les instructions de paiement et marque l’abonnement comme actif. Lors de la création, la valeur par défaut est `charge_automatically`. Si vous utilisez `send_invoice`, vous devez définir `days_until_due`.
`default_tax_rate`	ID Stripe Tax	`txr_1LPcLzAWeZvbCyjpzDA4qs1l`	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`	Timestamp	`1658179441`	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.
`days_until_due`	Nombre entier	`30`	Nombre de jours entre la création de la facture et son échéance. Cette valeur 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	`false`	Indique la valeur `true` si vous souhaitez annuler un abonnement à la fin de la période.

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 :

Attribut	Type	Exemple	Description
`customer` (obligatoire)	ID client Stripe	`cus_xxx1`	Identifiant du client pour lequel l’abonnement doit être créé.
`start_date` (obligatoire)	Horodatage au format epoch UNIX	`1658179441`	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.
`items.0.price` (obligatoire)	ID de tarif Stripe	`price_1LDGNmDK0D4Fox2RxIaXQkBp`	ID de l’objet Price. Doit être un tarif récurrent.
`items.0.quantity`	Nombre	`1`	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.1.price` (obligatoire)	ID de tarif Stripe	`price_1LujbnDCA5oQnOCew7kwa4T5`	ID de l’objet Price. Doit être un tarif récurrent.
`items.1.quantity`	Nombre	`1`	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_third_party_sub_id`	Chaîne	`subscription_1`	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	`false`	Indiquez `true` pour utiliser les paramètres fiscaux automatiques de Stripe Tax.
`billing_cycle_anchor`	Horodatage au format epoch UNIX	`1658179441`	Détermine la prochaine date de facturation de l’abonnement du client.
`coupon`	ID de bon de réduction Stripe	`50_off`	Identifiant du bon de réduction à appliquer à cet abonnement.
`proration_behavior`	Énumération	`create_prorations`	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`	Énumération	`charge_automatically` ou `send_invoice`	Lors d’un débit automatique, Stripe tente de payer l’abonnement sous-jacent à la fin de chaque période de facturation en utilisant la source par défaut associée au client. La valeur par défaut est `charge_automatically`. Lors de l’envoi d’une facture, Stripe envoie à votre client une facture par e-mail avec les instructions de paiement et marque l’abonnement comme actif. Si vous utilisez `send_invoice`, vous devez définir `days_until_due`.
`default_tax_rate`	ID Stripe Tax	`txr_1LPcLzAWeZvbCyjpzDA4qs1l`	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`	Timestamp	`1705753518`	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.
`days_until_due`	Nombre entier	`30`	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	`false`	Indique la valeur `true` si vous souhaitez annuler un abonnement à la fin de la période.
`add_invoice_items.0.amount`	Nombre	`19,99`	Un nombre positif. Utilisez des unités complètes with des décimales (par exemple, 21,50).
`add_invoice_items.0.product`	ID de produit Stripe	`prod_PjfC3kWS58IoOX`	Identifiant du produit auquel ajouter la facture.
`add_invoice_items.0.currency`	Chaîne	`usd`	Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge.

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 :

Attribut	Type	Exemple	Description
`customer` (obligatoire)	ID client Stripe	`cus_xxx1`	Identifiant du client pour lequel l’abonnement doit être créé.
`start_date` (obligatoire)	Horodatage au format epoch UNIX	`1710937191`	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.
`adhoc_items.0.amount` (obligatoire)	Nombre	`19,99`	Un nombre positif. Utilisez des unités complètes with des décimales (par exemple, 21,50).
`adhoc_items.0.product` (obligatoire)	ID de produit Stripe	`prod_NwSGSFZb7ENuTW`	Identifiant du produit qui correspond au tarif ad hoc.
`adhoc_items.0.interval` (obligatoire)	jour, semaine, mois ou année	`month`	Fréquence de facturation.
`adhoc_items.0.currency` (obligatoire)	Chaîne	`usd`	Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge.
`adhoc_items.0.quantity`	Nombre	`1`	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.1.amount`	Nombre	`19,99`	Un nombre positif. Utilisez des unités complètes with des décimales (par exemple, 21,50).
`adhoc_items.1.interval`	jour, semaine, mois ou année	`month`	Fréquence de facturation.
`adhoc_items.1.currency`	Chaîne	`usd`	Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge.
`adhoc_items.1.quantity`	Nombre	`1`	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`	Nombre	`external:zuora`	Associe ces paires clé-valeur à un objet. Cela est utile pour stocker des informations supplémentaires sur l’objet dans un format structuré. Vous pouvez ajouter tous les champs de métadonnées souhaités, par exemple `metadata_third_party_sub_id`. S’il s’agit d’une migration de Stripe vers Stripe, entrez `internal:Stripe`.
`metadata_third_party_sub_id`	Chaîne	`subscription_1`	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	`false`	Indiquez `true` pour utiliser les paramètres fiscaux automatiques de Stripe Tax.
`billing_cycle_anchor`	Horodatage au format epoch UNIX	`1713615591`	Détermine la prochaine date de facturation de l’abonnement du client.
`coupon`	ID de bon de réduction Stripe	`black_friday`	Identifiant du bon de réduction à appliquer à cet abonnement.
`proration_behavior`	Énumération	`create_prorations`	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`	Énumération	`charge_automatically` ou `send_invoice`	Lors d’un débit automatique, Stripe tente de payer l’abonnement sous-jacent à la fin de chaque période de facturation en utilisant la source par défaut associée au client. La valeur par défaut est `charge_automatically`. Lors de l’envoi d’une facture, Stripe envoie à votre client une facture par e-mail avec les instructions de paiement et marque l’abonnement comme actif. Si vous utilisez `send_invoice`, vous devez définir `days_until_due`.
`default_tax_rate`	ID Stripe Tax	`txr_1LPcLzAWeZvbCyjpzDA4qs1l`	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	`1705753518`	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.
`days_until_due`	Nombre entier	`30`	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	`false`	Indique la valeur `true` si vous souhaitez annuler un abonnement à la fin de la période.
`add_invoice_items.0.amount`	Nombre	`19,99`	Un nombre positif. Utilisez des unités complètes with des décimales (par exemple, 21,50).
`add_invoice_items.0.product`	ID de produit Stripe	`prod_PjfC3kWS58IoOX`	Identifiant du produit auquel ajouter la facture.
`add_invoice_items.0.currency`	Chaîne	`usd`	Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge.

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

Si le fichier que vous avez chargé comporte des erreurs, le kit d’outils affiche un récapitulatif des échecs. Pour corriger les erreurs :

Cliquez sur Télécharger le fichier pour vérifier les erreurs.
Vérifiez la colonne processing_error pour voir les erreurs.

Corrigez toutes les erreurs. Les erreurs courantes incluent :

Erreur	Résolution des problèmes
Dates non valides	Assurez-vous que toutes les dates sont au format d’horodatage epoch ou Unix.
Plage `start_date` incorrecte	Assurez-vous que la date de début `start_date` de chaque abonnement soit dans plus de 24 heures.
Données manquantes	Assurez-vous que chaque enregistrement contient les champs requis.
Tarif et taxe incompatibles	Veillez à ce que les tarifs respectifs pour les taux de taxe spécifiés aient le même `tax_behavior` (TTC ou hors taxes).

Cliquez sur Charger le fichier corrigé pour charger le fichier CSV corrigé (la taille du fichier CSV est limitée à 120 Mo).
Attendez que le nouveau processus de validation soit terminé pour voir l’état de validation le plus récent.

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

Vous pouvez migrer des abonnements avec une tarification forfaitaire, comme un plan de base à 100 USD par mois ou un plan avancé à 200 USD par mois. Ces abonnements peuvent avoir un ou plusieurs postes.

Exemple 1 (basique) : Migrez un abonnement mensuel de base de 100 USD avec une quantité de 2 à partir du 1er janvier. L’abonnement est encaissé automatiquement via le moyen de paiement par défaut.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	2	subscription_1					none	charge_automatically

Exemple 2 (postes à tarifs multiples) : Migrez les abonnements suivants à partir du 1er janvier pour qu’ils soient encaissés automatiquement via le moyen de paiement par défaut :

Un abonnement mensuel de base de 100 USD avec une quantité de 2
Un abonnement mensuel avancé de 200 USD avec une quantité de 1

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	items.0.price (obligatoire)	items.0.quantity	items.1.price	items.1.quantity	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	price_xxx2	subscription_1						none	charge_automatically

Exemple 3 (basique) : Migrez l’abonnement suivant à partir du 1er janvier pour qu’il soit encaissé automatiquement via le moyen de paiement par défaut :

Un abonnement mensuel de base de 100 USD avec une quantité de 2
Des frais additionnels de 20 USD pour les factures ad hoc

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	2	subscription_1					none	charge_automatically					50	prod_xxx1	usd

Vous pouvez également migrer des abonnements avec un tarif ad hoc, dans les cas où vous n’avez pas de montants de tarif fixes.

Exemple 4 (tarifs ad hoc) : Migrez l’abonnement suivant à partir du 1er janvier pour qu’il soit encaissé automatiquement via le moyen de paiement par défaut :

Un abonnement mensuel ad hoc de 153 USD avec une quantité de 1

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	adhoc_items.0.amount (obligatoire)	adhoc_items.0.product	adhoc_items.0.interval	adhoc_items.0.currency	adhoc_items.0.quantity	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	prod_xxx1	1	subscription_1						none	charge_automatically

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

Vous pouvez collecter le paiement des abonnements migrés automatiquement via le moyen de paiement enregistré par défaut ou en envoyant une facture que le client peut payer à la date d’échéance.

Exemple 1 (basique) : Migrez un abonnement annuel de 500 USD avec une quantité de 1 à partir du 1er janvier, avec encaissement via le moyen de paiement par défaut.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1					none	charge_automatically

Exemple 2 (basique) : Migrez un abonnement annuel de 500 USD avec une quantité de 1, à partir du 1er janvier. Cet abonnement est facturé via une facture envoyée au client, avec une date d’échéance de 30 jours.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1					none	send_invoice			30

Migrer les abonnements à différentes étapes de la période de service de l'abonnement

Exemple 1 (basique) : Migrer un abonnement dont le renouvellement est prévu. Par exemple, migrez un abonnement mensuel de 100 USD avec renouvellement au 1er janvier. L’abonnement est renouvelé le 1er de chaque mois.

Définissez start_date sur la date de renouvellement actuelle, afin que l’abonnement soit facturé immédiatement.
Définissez billing_cycle_anchor sur la date du prochain cycle de renouvellement.
Définissez proration_behavior sur la valeur none.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1		subscription_1		1706745600			none	charge_automatically

Exemple 2 (Simple) : migrer un abonnement payant au milieu d’une période de facturation. Par exemple, migrer un abonnement mensuel de 100 USD avec une date de début initiale au 25 décembre. La date de migration est le 1er janvier et l’abonnement se renouvelle le 25 de chaque mois.

Définissez backdate_start_date sur la date de début initiale de l’abonnement.
Définissez billing_cycle_anchor sur la prochaine date de renouvellement.
Définissez start_date sur la date de migration.
Définissez proration_behavior sur none pour éviter de facturer à nouveau le client et maintenir l’abonnement dans un état planifié jusqu’à la prochaine période de facturation.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1		subscription_1		1706140800			none	charge_automatically		1703462400

Exemple 3 (basique) : Migrer des abonnements avec des périodes d’essai. Par exemple, migrez un abonnement mensuel basique de 100 USD au 1er janvier. L’abonnement est en période d’essai jusqu’au 31 janvier. Une fois la période d’essai terminée, l’abonnement est facturé automatiquement via le moyen de paiement par défaut.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1				1706659200	none	charge_automatically		1703462400

Exemple 4 (basique) : migrer des abonnements en retard. Par exemple, migrez un abonnement mensuel de 100 USD dont la date de début du dernier cycle est le 25 décembre et qui n’a pas été payé. Migrez cet abonnement en milieu de cycle à partir du 1er janvier avec une date de renouvellement le 25 de chaque mois. Cela crée une facture au prorata du 1er janvier au 25 janvier pour laquelle Stripe peut essayer de collecter le paiement.

Pour migrer les abonnements qui sont dans un cycle actif mais qui n’ont pas été payés dans le système précédent, définissez proration_behavior sur create_prorations pour créer immédiatement une facture et collecter le paiement. Cela permet également d’entrer l’abonnement dans le flux de relance de Stripe si le paiement est toujours impayé.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1		1706140800			create_prorations	charge_automatically		1703462400

Exemple 5 : migrez les abonnements qui doivent être annulés à la fin du cycle. Après la migration, vous pouvez choisir de facturer ou non ces abonnements, en fonction du moment de la migration (en milieu de cycle ou au moment du renouvellement).

Ils sont annulés à la fin de cette période. Par exemple, migrez un abonnement mensuel basique de 100 USD au 1er janvier. Cet abonnement sera automatiquement annulé le 31 janvier.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1		1706140800			none	charge_automatically		1703462400			TRUE

Migrer des abonnements avec taxes

Exemple 1 (basique) : Migrez des abonnements pour calculer automatiquement les taxes en activant Stripe Tax. Par exemple, migrez un abonnement mensuel de 100 USD au 1er janvier en activant Stripe Tax pour calculer automatiquement la taxe.

Le kit d’outils de migration valide si vous avez activé Stripe Tax à l’avance et si les clients ont fourni les champs requis pour calculer la taxe automatiquement. Assurez-vous que vos clients fournissent les informations nécessaires avant la migration.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1	TRUE				none	charge_automatically

Exemple 2 (basique) : Migrez des abonnements et calculez les taxes à l’aide de taux de taxe manuels. Par exemple, pour migrer un abonnement mensuel basique de 100 USD au 1er janvier, avec une taxe de 10 % créée à l’aide de taux de taxe manuels :

Créez un taux de taxe manuel de 10 % dans le Dashboard(Catalogue de produits > Bons de réduction).
Utilisez l’ID du taux de taxe dans le modèle de migration au format CSV.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxx1	1704067200	price_xxx1	1	subscription_1	FALSE	1706140800			none	charge_automatically	txr_xxx1

Exemple 3 (basique) : si vous utilisez un prestataire de services fiscaux externe, tel qu’Avalara ou Vertex :

Pour les abonnements migrés pour lesquels la taxe est déjà calculée, laissez les champs automatic_tax et default_tax_rate vides dans le CSV.

Une fois les abonnements migrés et mis en service, ils suivent automatiquement les flux de travail d’intégration fiscale que vous avez configurés pour les nouveaux abonnements dans votre intégration Billing.

Migrer des abonnements avec des réductions

Le kit d’outils de migration ne prend en charge qu’un seul bon de réduction par abonnement.

Vous pouvez migrer des abonnements avec des réductions qui sont appliquées après la migration. Par exemple, pour migrer un abonnement mensuel de 100 USD au 1er janvier avec une réduction permanente de 10 % :

Créez un bon de réduction de 10 % dans le Dashboard(Catalogue de produits > Bons de réduction).
Utilisez le nom du bon de réduction dans le fichier CSV de migration.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.third_party_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end	add_invoice_items.0.amount	add_invoice_items.0.product	add_invoice_items.0.currency
CHAMP	cus_xxxx1	1704067200	price_xxx1	1	subscription_1			sample_coupon		none	charge_automatically

Migrer des abonnements entre comptes Stripe

Les étapes pour migrer les abonnements d’un compte Stripe à un autre sont les mêmes que lors d’une migration à partir d’un système tiers. Utilisez le kit d’outils de migration Billing pour exporter les données d’abonnement de votre fichier CSV depuis votre ancien compte Stripe.

Pour créer un fichier CSV pour une migration de Stripe à Stripe :

Exportez les abonnements de l’ancien compte Stripe via le Dashboard.
Utilisez l’exemple CSV suivant comme référence pour mapper les champs entre les anciens et nouveaux comptes Stripe.

ATTRIBUT	customer (obligatoire)	start_date (obligatoire)	price (obligatoire)	quantité	metadata.old_Stripe_sub_id	automatic_tax	billing_cycle_anchor	bon de réduction	trial_end	proration_behavior	collection_method	default_tax_rate	backdate_start_date	days_until_due	cancel_at_period_end
CHAMP	Champ d’exportation : ID du client (à partir de l’exportation du compte précédent)	Champ d’exportation : Fin de la période actuelle UTC (à partir de l’exportation du compte précédent)	ID de tarif respectif dans le nouveau compte	Champ d’exportation : quantité (à partir de l’exportation du compte précédent)	Champ d’exportation : id (à partir de l’exportation du compte précédent)	TRUE si vous utilisez Stripe Tax dans le nouveau compte, sinon FALSE	Future date de facturation dans le nouveau compte	Bon de réduction respectif dans le nouveau compte, le cas échéant	Période d’essai respective dans le nouveau compte, le cas échéant	`create_prorations` en cas de facture au prorata, sinon `none`	`charge_automatically` ou `send_invoice`	Taux de taxe respectif dans le nouveau compte, le cas échéant	Champ d’exportation : date de début UTC (à partir de l’exportation du compte précédent)	Précise l’utilisation ou non de `send_invoice` comme méthode d’encaissement	Indique si un abonnement doit être annulé à la fin de la période

Migrer des abonnements à plusieurs phases

Le kit d’outils de migration ne permet pas d’ajouter plusieurs phases directement à un abonnement. Nous recommandons l’approche suivante :

Utilisez le kit d’outils de migration pour migrer la phase initiale de l’abonnement.
Après la migration, ajoutez les phases supplémentaires aux planifications d’abonnements migrés. Pour ce faire, appelez le endpoint de mise à jour ou utilisez le Dashboard Abonnements Stripe.
Ajustez la start_date de la migration pour laisser suffisamment de temps entre les changements d’état planifiés et les changements d’état en temps réel. Cela vous permet d’effectuer les mises à jour de phase avant que les abonnements ne soient mis en production.

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	Un nombre positif. Utilisez des unités complètes with des décimales (par exemple, 21,50).
`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 d’un débit automatique, Stripe tente de payer l’abonnement sous-jacent à la fin de chaque période de facturation en utilisant la source par défaut associée au client. La valeur par défaut est `charge_automatically`. Lors de l’envoi d’une facture, Stripe envoie à votre client une facture par e-mail avec les instructions de paiement 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