# Migrate subscriptions to Stripe Billing using toolkit Learn how to migrate your existing subscriptions to Stripe using the toolkit. Use the [Billing migration toolkit](https://dashboard.stripe.com/billing/migrations) in the Stripe Dashboard to migrate your existing subscriptions from a third-party system, a home-grown system, or an existing Stripe account to Stripe Billing. ## Before you begin 1. If you haven’t already, review the [migration stages](https://docs.stripe.com/billing/subscriptions/migrate-subscriptions.md#migration-stages). 1. [Set up a Stripe Billing integration](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) before you begin migration. This is a one-time setup that you don’t need to repeat for future migrations. 1. [Request a payments data import](https://docs.stripe.com/get-started/data-migrations/pan-import.md) from your current processor. This step is only required if you’re migrating to Stripe from another processor. If you’re migrating from Stripe to Stripe, you can skip this prerequisite. 1. If you’re migrating from a third-party or home-grown system, carefully time the cancellation of your existing subscriptions and the creation of new ones in Stripe. To avoid missing a billing period, create the new subscriptions in Stripe first, before canceling the old subscriptions. To avoid double billing, cancel subscriptions in your old system before the subscriptions are set to charge. For subscriptions with upcoming billing dates close to migration, schedule them to start after the cycle so the final bill is in the old system. ## Open the Billing migration toolkit Create a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) in the Dashboard if you want to run a test migration first. 1. Go to [Dashboard](https://dashboard.stripe.com/billing) > [Subscriptions](https://dashboard.stripe.com/test/subscriptions) > [**Migrations**](https://dashboard.stripe.com/test/billing/migrations). Alternatively, you can click the overflow menu (⋯) next to **+ Create subscription**, and select [Migrate subscriptions](https://dashboard.stripe.com/settings/billing/migrations). 1. To start your migration, click **Let’s get started**. ## Download a CSV file First, export your existing subscriptions by matching the exported data to a migration-compatible CSV file. You can create your own CSV file, or download any of the following CSV templates provided by Stripe ([Basic](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#basic), [Multi-price items](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#multi-price), and [Ad-hoc pricing](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#ad-hoc)). You can also find examples of CSV files for common migration [use cases](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#migration-use-cases). 1. Click **Download CSV template**. 1. Choose a CSV template (basic, multi-price items, or ad-hoc pricing) based on your billing use case. ### Basic CSV This example shows a migration for common subscription use cases like quantity, taxes, billing anchor, discounts, trials, and backdating. ### Specify the following fields for a Basic CSV file: | Attribut | Saisir | Example | Description | | --------------------------- | ------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` **(required)** | Stripe Customer ID | `cus_xxx1` | The identifier of the customer to create the subscription for. | | `start_date` **(required)** | Timestamp in epoch UNIX format | `1658179441` | Determines when to create the subscription. You must provide a value that’s 24 hours (or greater) into the future. In a sandbox, you can set this to 1 hour in the future. | | `price` **(required)** | Stripe Price ID | `price_1LDGNmDK0D4Fox2RxIaXQkBp` | You must use a recurring price. If migrating multiple items, use the `items.x.{price, quantity}` format instead. Ad-hoc prices are also supported with `adhoc_items.x.{amount, product, interval,currency}`. | | `quantity` | Numéro | `1` | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `metadata.*` | Chaîne | `subscription_1` | Attach these key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. You can add any metadata fields you desire (for example, `metadata_third_party_sub_id`). If this is a Stripe-to-Stripe migration, enter `internal:Stripe`. | | `automatic_tax` | Boolean | `false` | Specify `true` to use automatic tax settings by Stripe Tax. | | `billing_cycle_anchor` | Timestamp in epoch UNIX format | `1658179441` | Determines the next date to bill the subscription to the customer. | | `coupon` | Stripe Coupon ID | `Z4OV52SU` | The identifier of the coupon to apply to this subscription. | | `trial_end` | Timestamp in epoch UNIX format | `1658179441` | Sets the phase to trialing from the start date to the `trial_end` date. You must specify a value that’s before the cycle end date, and you can’t combine it with the trial. | | `proration_behavior` | Enum | `create_prorations` or `none` | Determines if the subscription creates prorations after migration. The default value is `create_prorations`. | | `collection_method` | Enum | `charge_automatically` or `send_invoice` | When charging automatically, Stripe attempts to pay the underlying subscription at the end of each billing period using the default source attached to the customer. When sending an invoice, Stripe emails your customer an invoice with payment instructions and mark the subscription as active. On creation, this defaults to `charge_automatically`. If `send_invoice`, you must set `days_until_due`. | | `default_tax_rate` | Stripe Tax ID | `txr_1LPcLzAWeZvbCyjpzDA4qs1l` | Sets the subscription’s `default_tax_rates`. This also determines the invoice’s `default_tax_rates` for any invoices issued by the subscription during this phase. This value is incompatible with `automatic_tax`. | | `backdate_start_date` | Timestamp | `1658179441` | Determines the `start_date` of the created subscription, which must occur in the past. If set, you must specify `none` for the `proration_behavior`. Doing so prevents the creation of a prorated invoice for the time between `backdate_start_date` and actual `start_date`. For more details, see [backdating no charge](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-no-charge). | | `days_until_due` | Integer | `30` | The number of days from when the invoice is created until it’s due. This value is required and valid only for invoices with `collection_method` set to `send_invoice`. | | `cancel_at_period_end` | Boolean | `false` | Specify `true` if you want to cancel a subscription at the end of the period. | ### Multi-price items CSV This example shows a migration that has multiple products per subscription. ### Specify the following fields for a Multi-price items CSV file: | Attribut | Saisir | Example | Description | | ------------------------------- | ------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` **(required)** | Stripe Customer ID | `cus_xxx1` | The identifier of the customer to create the subscription for. | | `start_date` **(required)** | Timestamp in epoch UNIX format | `1658179441` | Determines when to create the subscription. You must provide a value that’s 24 hours (or greater) into the future. In a sandbox, you can set this to 1 hour in the future. | | `items.0.price` **(required)** | Stripe Price ID | `price_1LDGNmDK0D4Fox2RxIaXQkBp` | The identifier of the price object, which must be a recurring price. | | `items.0.quantity` | Numéro | `1` | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `items.1.price` **(required)** | Stripe Price ID | `price_1LujbnDCA5oQnOCew7kwa4T5` | The identifier of the price object, which must be a recurring price. | | `items.1.quantity` | Numéro | `1` | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `metadata_third_party_sub_id` | Chaîne | `subscription_1` | Attach these key-value pairs to an object. This is useful for storing additional information about the object in a structured format. | | `automatic_tax` | Boolean | `false` | Specify `true` to use automatic tax settings by Stripe Tax. | | `billing_cycle_anchor` | Timestamp in epoch UNIX format | `1658179441` | Determines the next date to bill the subscription to the customer. | | `coupon` | Stripe Coupon ID | `Z4OV52SU` | The identifier of the coupon to apply to this subscription. | | `proration_behavior` | Enum | `create_prorations` | Determines if the subscription creates prorations after migration. The default value is `create_prorations`. | | `collection_method` | Enum | `charge_automatically` or `send_invoice` | When charging automatically, Stripe attempts to pay the underlying subscription at the end of each billing period using the default source attached to the customer. The default value is `charge_automatically`. When sending an invoice, Stripe emails your customer an invoice with payment instructions, and marks the subscription as active. If using `send_invoice`, you must set `days_until_due`. | | `default_tax_rate` | Stripe Tax ID | `txr_1LPcLzAWeZvbCyjpzDA4qs1l` | Sets the subscription’s `default_tax_rates`. This also determines the invoice’s `default_tax_rates` for any invoices issued by the subscription during this phase. This value is incompatible with `automatic_tax`. | | `backdate_start_date` | Timestamp | `1705753518` | Determines the `start_date` of the created subscription, which must occur in the past. If set, you must specify `none` for the `proration_behavior`. Doing so prevents the creation of a prorated invoice for the time between `backdate_start_date` and actual `start_date`. For more details, see [backdating no charge](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-no-charge). | | `days_until_due` | Integer | `30` | The number of days from when the invoice is created until it’s due. This is required and valid only for invoices with `collection_method` set to `send_invoice`. | | `cancel_at_period_end` | Boolean | `false` | Specify `true` if you want to cancel a subscription at the end of the period. | | `add_invoice_items.0.amount` | Numéro | `19.99` | A positive number. Use full units with decimals (such as 21.50). | | `add_invoice_items.0.product` | Stripe Product ID | `prod_PjfC3kWS58IoOX` | The identifier of the product to add the invoice to. | | `add_invoice_items.0.currency` | Chaîne | `usd` | A three-letter ISO currency code, in lowercase, for a [supported currency](https://docs.stripe.com/currencies.md). | ### Ad-hoc prices CSV This example shows handling a subscription migration using [ad-hoc pricing](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data) for existing products. ### Specify the following fields for an Ad-hoc pricing CSV file: | Attribut | Saisir | Example | Description | | --------------------------------------- | ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` **(required)** | Stripe Customer ID | `cus_xxx1` | The identifier of the customer to create the subscription for. | | `start_date` **(required)** | Timestamp in epoch UNIX format | `1710937191` | Determines when to create the subscription. You must provide a value that’s 24 hours (or greater) into the future. In a sandbox, you can set this to 1 hour in the future. | | `adhoc_items.0.amount` **(required)** | Numéro | `19.99` | A positive number. Use full units with decimals (such as 21.50). | | `adhoc_items.0.product` **(required)** | Stripe Product ID | `prod_NwSGSFZb7ENuTW` | The identifier of the product that belongs with the ad-hoc price. | | `adhoc_items.0.interval` **(required)** | day, week, month or year | `month` | The billing frequency. | | `adhoc_items.0.currency` **(required)** | Chaîne | `usd` | A three-letter ISO currency code, in lowercase, for a [supported currency](https://docs.stripe.com/currencies.md). | | `adhoc_items.0.quantity` | Numéro | `1` | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `adhoc_items.1.amount` | Numéro | `19.99` | A positive number. Use full units with decimals (such as 21.50). | | `adhoc_items.1.interval` | day, week, month or year | `month` | The billing frequency. | | `adhoc_items.1.currency` | Chaîne | `usd` | A three-letter ISO currency code, in lowercase, for a [supported currency](https://docs.stripe.com/currencies.md). | | `adhoc_items.1.quantity` | Numéro | `1` | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `metadata.source` | Numéro | `external:zuora` | Attach these key-value pairs to an object. This is useful for storing additional information about the object in a structured format. You can add any metadata fields desired, for example `metadata_third_party_sub_id`. If this is a Stripe-to-Stripe migration, enter `internal:Stripe`. | | `metadata_third_party_sub_id` | Chaîne | `subscription_1` | Attach these key-value pairs to an object. This is useful for storing additional information about the object in a structured format. | | `automatic_tax` | Boolean | `false` | Specify `true` to use automatic tax settings by Stripe Tax. | | `billing_cycle_anchor` | Timestamp in epoch UNIX format | `1713615591` | Determines the next date to bill the subscription to the customer. | | `coupon` | Stripe Coupon ID | `black_friday` | The identifier of the coupon to apply to this subscription. | | `proration_behavior` | Enum | `create_prorations` | Determines if the subscription creates prorations after migration. The default value is `create_prorations`. | | `collection_method` | Enum | `charge_automatically`or `send_invoice` | When charging automatically, Stripe attempts to pay the underlying subscription at the end of each billing period using the default source attached to the customer. The default value is `charge_automatically`. When sending an invoice, Stripe emails your customer an invoice with payment instructions, and marks the subscription as active. If using `send_invoice`, you must set `days_until_due`. | | `default_tax_rate` | Stripe Tax ID | `txr_1LPcLzAWeZvbCyjpzDA4qs1l` | Sets the subscription’s `default_tax_rates`. This also determines the invoice’s `default_tax_rates` for any invoices issued by the subscription during this Phase. This value is incompatible with `automatic_tax`. | | `backdate_start_date` | Timestamp in epoch UNIX format | `1705753518` | Determines the `start_date` of the created subscription, which must occur in the past. If set, you must specify `none` for the `proration_behavior`. Doing so prevents the creation of a prorated invoice for the time between `backdate_start_date` and actual `start_date`. For more details, see [backdating no charge](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-no-charge). | | `days_until_due` | Integer | `30` | The number of days from when the invoice is created until it’s due. This is required and valid only for invoices with `collection_method` set to `send_invoice`. | | `cancel_at_period_end` | Boolean | `false` | Specify `true` if you want to cancel a subscription at the end of the period. | | `add_invoice_items.0.amount` | Numéro | `19.99` | A positive number. Use full units with decimals (such as 21.50). | | `add_invoice_items.0.product` | Stripe Product ID | `prod_PjfC3kWS58IoOX` | The identifier of the product to add the invoice to. | | `add_invoice_items.0.currency` | Chaîne | `usd` | A three-letter ISO currency code, in lowercase, for a [supported currency](https://docs.stripe.com/currencies.md). | 1. In the CSV file, specify the details of the subscriptions you want to export. > #### For Stripe-to-Stripe migrations > > If you’re migrating subscriptions within Stripe accounts, refer to the [CSV example](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#within-Stripe-accounts) before you specify and upload a CSV file. ## Upload a CSV file Click **Upload CSV**. The CSV file size limit is 120 MB. Stripe validates the file to verify that the uploaded subscriptions are in the required CSV format. This process might take up to a few hours, depending on the size of the file. If the file is valid, you can proceed to the next step in the migration. If there are any validation errors, you must [resolve the errors](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#resolve-validation-errors) to proceed. ## Review uploaded subscriptions After Stripe validates your CSV file, review the summary of your uploaded subscriptions for any discrepancies: 1. Cross-check the summary for the correct: - Date of upload - Uploaded file name - Number of subscriptions - Number of customers - First subscription go-live date 1. If everything is valid, click **Start migration**. If you see errors, click **Cancel migration** and restart the migration from [Download a CSV file](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#download-csv). ## Track migration progress After you review your uploaded subscriptions, track the progress of your migration: | Migration progress | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | La migration est en cours | Your subscriptions are queued to schedule on the specified start date. This process can take a few minutes to a few hours, depending on the size of the file. For example, the validation and migration for 100,000 subscriptions takes approximately 30 minutes to complete. The Billing migration toolkit uses the [Subscription schedule](https://docs.stripe.com/api/subscription_schedules.md) to migrate your subscriptions. This allows your subscriptions to remain in a scheduled state for 24 hours before going live. In a sandbox, the buffer time is reduced to 1 hour for faster evaluation and testing. | | Scheduled subscriptions | After migration, your subscriptions remain in a scheduled state for 24 hours before going live. You have 10 hours to [cancel these scheduled subscriptions](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#cancel-migration) using the toolkit. You can’t update scheduled subscriptions using the migration toolkit. If you want to update your scheduled subscriptions, you can either call the [update](https://docs.stripe.com/api/subscription_schedules/update.md) endpoint, or update each subscription individually in the [Subscriptions](https://dashboard.stripe.com/subscriptions) page of the Dashboard. Customers can’t cancel scheduled subscriptions from their customer portal. They can only cancel live subscriptions. | | Go live with subscriptions | After 24 hours, your scheduled subscriptions go live and charge customers on their applicable start dates. You can view all your live subscriptions in the [Subscriptions](https://dashboard.stripe.com/subscriptions) page of the Dashboard. After the migration goes live, we recommend you monitor your subscriptions starting from the first payment. Make sure the charge dates and amounts for the migrated subscriptions match the specified [start_date](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-start_date). Customers can cancel live subscriptions from their customer portal. | | Monitor subscriptions | After the migration goes live, monitor your subscriptions for problems related to payment methods. For example, check transactions for unrecoverable issuer [decline codes](https://docs.stripe.com/declines/codes.md) such as `incorrect_number` and [take action](https://docs.stripe.com/get-started/data-migrations/pan-import.md#remap-customer-ids) to make sure invoices get paid. Consider notifying customers that have invalid payment methods through channels other than email, such as text messages or in-app notifications. When using automatic collection, check [open or past due invoices](https://docs.stripe.com/billing/collection-method.md#failed-incomplete-subscriptions) to make sure customers aren’t missing [default payment methods](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-payment_settings-save_default_payment_method), which might cause the invoice to be unable to attempt collection. | ## View all migrations To view all of your migrations: 1. Select the migration you want to review in [**Migrations**](https://dashboard.stripe.com/billing/migrations). 1. To open a migration, click **View** in the dropdown menu. You can track the following fields: - Upload date - Nom du fichier - Stripe billing migration id - Number of subscriptions - Migration status ## Optional: Cancel a migration If you identify any problems with the scheduled subscriptions, you can roll back the migration and revert the scheduled subscriptions. The Dashboard displays a timestamp to indicate if you can still cancel the migration using the toolkit. You have 10 hours from when you scheduled the subscriptions to cancel them. After 10 hours, the cancel option is disabled in the toolkit. To cancel the migration after 10 hours, you can either call the [cancel](https://docs.stripe.com/api/subscription_schedules/cancel.md) endpoint, or individually cancel each subscription in the [Subscriptions](https://dashboard.stripe.com/subscriptions) page of the Dashboard. 1. Find the migration you want to cancel in your [Migrations](https://dashboard.stripe.com/billing/migrations). 1. Click **Cancel migration** in the dropdown menu. ## Optional: Run multiple migrations You can run as many simultaneous subscription migrations as you want. For large migrations, divide the subscriptions into batches and start with a small batch. This can help you quickly identify any validation issues and save validation time. To start a new migration: 1. Click **Start new migration**. 1. Restart the migration process from [Download a CSV file](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#download-csv). You can also find examples of CSV files for common migration [use cases](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#migration-use-cases). ## Optional: Resolve validation errors If you have any errors in your uploaded file, the toolkit displays a failure summary. To resolve the errors: 1. Click **Download file to review errors**. 1. Review the `processing_error` column to see the errors. 1. Correct all the errors. Common errors include: | Erreur | Résolution des problèmes | | ---------------------------- | --------------------------------------------------------------------------------------------------- | | Invalid dates | Make sure all the dates are in epoch or Unix timestamp format. | | Incorrect `start_date` range | Make sure the `start_date` for each subscription is at least 24 hours in the future. | | Missing data | Make sure every record contains the required fields. | | Incompatible price and tax | Make sure prices for specified tax rates have the same `tax_behavior` (inclusive versus exclusive). | 1. Click **Upload revised file** to re-upload the corrected CSV (the CSV file size limit is 120 mb). 1. Wait for re-validation to see the latest validation status. ## Migration use cases You can apply the migration use cases in this section to your own migration, if applicable. Timestamps in these examples are in Unix EPOCH format. The examples also include test customer and price IDs that you can use in a sandbox. You can combine any Stripe-provided CSV template ([Basic](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#basic), [Multi-price items](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#multi-price), [Ad-hoc pricing](https://docs.stripe.com/billing/subscriptions/import-subscriptions-toolkit.md#ad-hoc)) with any of these examples as needed. ### Migrate subscriptions with various pricing models 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. **Example 1 (Basic)**: Migrate a basic 100 USD monthly subscription with a quantity of 2, starting on January 1. The subscription is charged automatically using the default payment method. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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 | | | | | | | | **Example 2 (Multi-price items)**: Migrate the following subscriptions starting on January 1, to be charged automatically using the default payment method: - 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 | | | | | | | | | **Example 3 (Basic)**: Migrate the following subscription starting on January 1, to be charged automatically using the default payment method: - 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 | 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. **Example 4 (Ad-hoc pricing)**: Migrate the following subscription starting on January 1, to be charged automatically using the default payment method: - 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 | | | | | | | | | ### Migrate subscriptions with different types of payment collection methods 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. **Example 1 (Basic)**: Migrate a yearly 500 USD subscription with a quantity of 1, starting on January 1, to be charged automatically using the default payment method. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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 | | | | | | | | **Example 2 (Basic)**: Migrate a yearly 500 USD subscription with a quantity of 1, starting on January 1. This subscription is billed using an invoice sent to the customer, with a 30-day due date. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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 | | | | | ### Migrate subscriptions at different stages of subscription service period **Example 1 (Basic): Migrate a subscription that’s due for renewal**. For example, migrate a 100 USD monthly subscription with a renewal date of January 1. The subscription renews on the 1st of every month. - 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 | 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 | | | | | | | | **Example 2 (Basic): Migrate a paid subscription that’s in the middle of a billing period**. For example, migrate a 100 USD monthly subscription with an original start date of December 25. The migration date is January 1, and the subscription renews on the 25th of every month. - 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. - Set `proration_behavior` to `none` to avoid charging the customer again and keep the subscription in a scheduled state until the next billing period. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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 | | | | | | **Example 3 (Basic): Migrate subscriptions with trials**. For example, migrate a basic 100 USD monthly subscription starting on January 1. The subscription is under a trial until January 31. After the trial ends, the subscription is charged automatically using the default payment method. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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_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 | 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). They’re canceled at the end of that period. For example, migrate a basic 100 USD monthly subscription starting on January 1. This subscription is automatically canceled on January 31. | | | | | **ATTRIBUT** | customer (obligatoire) | start_date (obligatoire) | price (obligatoire) | quantité | 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 | | | ### Migrate subscriptions with taxes **Example 1 (Basic)**: Migrate subscriptions to automatically calculate tax by enabling Stripe Tax. For example, migrate a 100 USD monthly subscription starting January 1, with Stripe Tax enabled to calculate the tax automatically. 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 | 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 | | | | | | | | **Example 2 (Basic)**: Migrate subscriptions and calculate tax using [manual tax rates](https://dashboard.stripe.com/test/tax-rates). For example, to migrate a basic 100 USD monthly subscription starting on January 1, with 10% tax created using manual tax rates: - Créez un taux de taxe manuel de 10 % dans le [Dashboard](https://dashboard.stripe.com/test/tax-rates)**(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 | 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_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. ### Migrate subscriptions with discounts The migration toolkit supports only one coupon per subscription. You can migrate subscriptions with discounts that are applied after migration. For example, to migrate a 100 USD monthly subscription starting January 1, with a 10% forever discount: - Créez un bon de réduction de 10 % dans le [Dashboard](https://dashboard.stripe.com/test/tax-rates)**(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 | 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 | | | | | | | | ### Migrate subscriptions within Stripe accounts The steps to migrate subscriptions from one Stripe account to another are the same as when migrating from a third-party system. Use the Billing migration toolkit to export the subscription data for your CSV file from your old Stripe account. To create a migration CSV for a Stripe-to-Stripe migration: 1. Exportez les abonnements de l’ancien compte Stripe via le Dashboard. 1. 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 | 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_prorations` en cas de facture au prorata, sinon `none` | `charge_automatically` or `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 | ### Migrate subscriptions with multiple phases Le kit d’outils de migration ne permet pas d’ajouter plusieurs phases directement à un abonnement. Nous recommandons l’approche suivante : 1. Utilisez le kit d’outils de migration pour migrer la phase initiale de l’abonnement. 1. Après la migration, ajoutez les phases supplémentaires aux planifications d’abonnements migrés. Pour ce faire, appelez le endpoint de [mise à jour](https://docs.stripe.com/api/subscription_schedules/update.md) ou utilisez le Dashboard [Abonnements](https://dashboard.stripe.com/test/subscriptions) Stripe. 1. 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. ## CSV reference The migration tookit requires you to upload a CSV that has specific information in the correct fields. ### Prérequis CSV Before you create or download a CSV file, make sure you have access to the following information: | | | | | \** Objet Customer** | Tous les clients doivent disposer d’un [moyen de paiement](https://docs.stripe.com/api/payment_methods/attach.md) 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 : - Obtenir le consentement de l’utilisateur ou se baser sur son comportement de paiement antérieur pour déterminer le moyen de paiement par défaut, par client. - Utiliser ce [script](https://gist.github.com/bsears90/c3f36bfe379dfd13cae749824c5b45ae) pour associer le moyen de paiement le plus récent à vos clients et le définir comme moyen de paiement par défaut. | | \** impôt (when referring to income tax) automatique ** | If you use Stripe Tax (where you set automatic tax to true), all customers must have either [addresses or postal codes](https://docs.stripe.com/tax/customer-locations.md) (or both) per country. Stripe needs this information to calculate taxes for the given subscriptions. | | [collection_method](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-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](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-days_until_due) dans le fichier CSV de migration pour indiquer la validité des *factures* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) de chaque client. | | **Date** | - 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) 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** | - If the subscription schedule or subscription has [billing cycle anchor](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) in the future and `proration_behavior` [set to](https://docs.stripe.com/billing/subscriptions/prorations.md#disable-prorations) `none`, updating these objects unsets the coupon. Re-apply the coupon if you make any updates to the subscription schedule or subscription. - 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 de Stripe à Stripe ** | Les utilisateurs peuvent migrer les abonnements des comptes Stripe . Vous devez saisir les ID de Client et de tarif (ainsi que les ID de bon de Bon de réduction et les ID de Impôt (when referring to income tax) , le cas échéant) 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 saisissez les ID associés à votre compte source. | ### Full CSV specification | Attribut | Saisir | Description | | ------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` **(required)** | Stripe Customer ID | The identifier of the customer to create the subscription for. | | `start_date` **(required)** | Timestamp in epoch UNIX format | Determines when to create the subscription. You must provide a value that’s 24 hours (or greater) into the future. In a sandbox, you can set this to 1 hour in the future. | | `price` **(required)** | Stripe Price ID | Must be a recurring price. If migrating multiple items, use `items.x.{price, quantity}` format instead. Ad-hoc prices are also supported with `adhoc_items.x.{amount, interval, product, currency}`. | | `quantity` | Numéro | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `items.x.price` **(obligatoire)** | Stripe Price ID | L’ID de l’objet Price. Doit être un tarif récurrent. | | `items.x.quantity` | Numéro | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `adhoc_items.x.amount` **(obligatoire)** | Numéro | A positive number. Use full units with decimals (such as 21.50). | | `adhoc_items.x.product` **(obligatoire)** | Stripe Product ID | The identifier of the product that belongs with the ad-hoc price. | | `adhoc_items.x.interval` **(obligatoire)** | `day`, `week`, `month` or `year` | The billing frequency. | | `adhoc_items.x.currency` **(obligatoire)** | Chaîne | A three-letter ISO currency code, in lowercase, for a [supported currency](https://docs.stripe.com/currencies.md). | | `adhoc_items.x.quantity` | Numéro | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. | | `metadata_source` | Chaîne | Si vous effectuez une migration Stripe vers Stripe, saisissez `internal:Stripe`. | | `metadata_*` | Chaîne | Attach these key-value pairs to an object. This is useful for storing additional information about the object in a structured format. | | `automatic_tax` | Boolean | Specify `true` to use automatic tax settings by Stripe Tax. | | `coupon` | Stripe Coupon ID | The identifier of the coupon to apply to this subscription. | | `currency` | Chaîne | [Code de devise ISO](https://www.iso.org/iso-4217-currency-codes.html) à trois lettres en minuscules. Il doit s’agir d’une [devise prise en charge](https://docs.stripe.com/currencies.md). 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` or `none` | Determines if the subscription creates prorations after migration. The default value is `create_prorations`. | | `collection_method` | `charge_automatically` or `send_invoice` | When charging automatically, Stripe attempts to pay the underlying subscription at the end of each billing period using the default source attached to the customer. The default value is `charge_automatically`. When sending an invoice, Stripe emails your customer an invoice with payment instructions, and marks the subscription as active. If using `send_invoice`, you must set `days_until_due`. | | `default_tax_rate` | Stripe Tax ID | Sets the subscription’s `default_tax_rates`. This also determines the invoice’s `default_tax_rates` for any invoices issued by the subscription during this phase. This value is incompatible with `automatic_tax`. | | `backdate_start_date` | Timestamp in epoch UNIX format | Determines the `start_date` of the created subscription, which must occur in the past. If set, you must specify `none` for the `proration_behavior`. Doing so prevents the creation of a prorated invoice for the time between `backdate_start_date` and actual `start_date`. For more details, see [backdating no charge](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-no-charge). | | `billing_cycle_anchor` | Timestamp | Détermine les dates futures de facturation de l’abonnement du client. | | `days_until_due` | Integer | The number of days from when the invoice is created until it’s due. This is required and valid only for invoices with `collection_method` set to `send_invoice`. | | `cancel_at_period_end` | Boolean | Indique la valeur `true` pour annuler un abonnement à la fin de la période. | ## See also - [Migrate subscriptions using Stripe APIs](https://docs.stripe.com/billing/subscriptions/import-subscriptions.md)