Référence pour le fichier CSV du kit d'outils
Suivez les bonnes pratiques pour migrer efficacement vos abonnements à l'aide du kit d'outils Billing sans code.
Ce guide vous aidera à spécifier votre fichier CSV dans le kit d’outils de migration Billing. Dans les exemples suivants, tous les horodatages sont au format Unix EPOCH. Nous fournissons également des ID de clients et de tarif de test que vous pouvez utiliser en mode test.
Prérequis CSV
Avant de créer ou de télécharger un fichier CSV, assurez-vous de connaître les points suivants :
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 :
|
Calcul automatique des taxes | Si vous utilisez Stripe Tax (où vous avez activé le calcul automatique des taxes), tous les clients doivent avoir des adresses et/ou des codes postaux par pays. Stripe utilisera cette information pour calculer les taxes à appliquer pour certains abonnements. |
collection_method | Si vous utilisez le moyen de paiement send_ pour vos abonnements :
|
Dates |
|
Bons de réduction |
|
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. |
Cas d’usage de migration
Vous pouvez appliquer les cas d’usage de migration ci-dessous à votre propre migration, le cas échéant :
- Migrer des abonnements avec différents modèles tarifaires
- Migrer des abonnements avec différentes méthodes d’encaissement des paiements
- Migrer les abonnements à différents stades du cycle d’abonnement
- Migrer des abonnements avec des taxes
- Migrer des abonnements avec des réductions
- Migrer des abonnements entre des comptes Stripe
- Migrer des abonnements à plusieurs phases
Vous pouvez combiner n’importe quel modèle CSV fourni par Stripe (Basique, Articles à prix multiples, Tarifs ad hoc) avec n’importe lequel des exemples ci-dessous 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) : migrer un abonnement mensuel de base de 100 USD avec une quantité de 2, à partir du 1er janvier 2024. L’abonnement est facturé automatiquement à l’aide du moyen de paiement par défaut.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 (articles à prix multiples) : migrez les abonnements suivants à partir du 1er janvier 2024 pour qu’ils soient facturé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 | coupon | 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) : migrer l’abonnement suivant à partir du 1er janvier 2024 pour qu’il soit facturé 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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 suivants à partir du 1er janvier 2024 pour qu’il soit facturés 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 | coupon | 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) : migrer un abonnement annuel de 500 USD avec une quantité de 1 à partir du 1er janvier 2024, pour qu’il soit facturé automatiquement via le moyen de paiement par défaut.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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) : migrer un abonnement annuel de 500 USD avec une quantité de 1 à partir du 1er janvier 2024. 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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 des abonnements à différents stades du cycle d’abonnement
Exemple 1 (basique) : migrer un abonnement dont le renouvellement est prévu. Par exemple, migrez un abonnement mensuel de 100 USD dont la date de renouvellement est le 1er janvier 2024. L’abonnement est renouvelé le 1er de chaque mois.
- Définissez
start_
sur la date de renouvellement actuelle, afin que l’abonnement soit facturé immédiatement.date - Définissez
billing_
sur la date du prochain cycle de renouvellement.cycle_ anchor - Définissez
proration_
sur la valeurbehavior none
.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 (basique) : migrer un abonnement payant qui se trouve au milieu d’un cycle de facturation. Par exemple, migrez un abonnement mensuel de 100 USD dont la date de début initiale est le 25 décembre. La date de migration est le 1er janvier et l’abonnement est renouvelé le 25 de chaque mois.
- Définissez
backdate_
sur la date de début initiale de l’abonnement.start_ date - Définissez
billing_
sur la prochaine date de renouvellement.cycle_ anchor - Définissez
start_
sur la date de migration.date - Définissez
proration_
sur la valeurbehavior none
pour éviter de facturer à nouveau le client et maintenir l’abonnement dans un état planifié jusqu’au prochain cycle de facturation.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 en périodes d’essai. Par exemple, migrez un abonnement mensuel de base de 100 USD à partir du 1er janvier 2024. L’abonnement est en période d’essai jusqu’au 31 janvier 2024. Après la fin de la période d’essai, l’abonnement est facturé automatiquement via le moyen de paiement par défaut.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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_
sur create_
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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 à partir du 1er janvier 2024. Cet abonnement est automatiquement annulé le 31 janvier 2024.
ATTRIBUT | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 des taxes
Exemple 1 (basique) : migrer des abonnements pour calculer automatiquement la taxe en activant Stripe Tax. Par exemple, migrez un abonnement mensuel de 100 USD à partir du 1er janvier 2024 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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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) : migrer des abonnements et calculer la taxe à l’aide des taux de taxe manuels. Par exemple, pour migrer un abonnement mensuel basique de 100 $ à partir du 1er janvier 2024, avec une taxe de 10 % créée à l’aide des 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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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_
et default_
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 actuellement en charge qu’un seul bon de réduction par abonnement.
Exemple 1 (basique) : 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 $ à partir du 1er janvier 2024, 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) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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 des 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 migrer les abonnements. Vous devrez exporter les données d’abonnement pour votre fichier CSV depuis votre ancien compte Stripe.
Exemple 1 (basique) : pour créer un fichier CSV de migration pour une migration Stripe vers 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) | quantity | metadata.old_Stripe_sub_id | automatic_tax | billing_cycle_anchor | coupon | 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_ en cas de facture au prorata, sinon none | charge_ ou send_ | 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_ 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_
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.date
Spécification CSV complète
Attribut | Type | Description |
---|---|---|
customer (obligatoire) | ID du client Stripe | Identifiant du client pour lequel l’abonnement doit être créé. |
start_ (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. En mode test, vous pouvez fixer cette valeur à 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. . Les tarifs ad hoc sont également pris en charge avec adhoc_ . |
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. (obligatoire) | ID de tarif Stripe | L’ID de l’objet Price. Doit être un tarif récurrent. |
items. | 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_ (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_ (obligatoire) | ID de produit Stripe | Identifiant du produit qui correspond au tarif ad hoc. |
adhoc_ (obligatoire) | day , week , month ou year | Fréquence de facturation. |
adhoc_ (obligatoire) | Chaîne | Code ISO de devise à trois lettres, en minuscules, pour une devise prise en charge. |
adhoc_ | 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_ | 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_ | 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_ | Horodatage | Définit la phase de la période d’essai entre la date de début et la date de trial_ . 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_ | create_ ou none | Détermine si l’abonnement crée des calculs au prorata après la migration. La valeur par défaut est create_ . |
collection_ | charge_ ou send_ | 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_ . 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_ , vous devez définir days_ . |
default_ | ID Stripe Tax | Définit les default_ par défaut de l’abonnement. Cela détermine également les taux default_ de la facture pour toutes les factures émises par l’abonnement au cours de cette phase. Cette valeur est incompatible avec automatic_ . |
backdate_ | Horodatage au format epoch UNIX | Détermine la start_ de l’abonnement créé, qui doit se situer dans le passé. Si cette option est activée, vous devez définir proration_ sur la valeur none . Cela empêche la création d’une facture au prorata pour la période comprise entre la date backdate_ et la date start_ réelle. Pour en savoir plus, veuillez consulter la section antidater sans facturer les utilisateurs. |
billing_ | Horodatage | Détermine les dates futures de facturation de l’abonnement du client. |
days_ | 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_ est définie sur send_ . |
cancel_ | Booléen | Indique la valeur true pour annuler un abonnement à la fin de la période. |