Migrate to Stripe Tax
Learn how to migrate existing subscriptions to Stripe Tax.
Stripe Tax allows you to calculate the tax to collect on your transactions. It computes the taxes and adds them to the payment automatically, based on the product and the customer location.
When you integrate with Stripe Tax, you need to update existing subscriptions to make sure that tax is automatically calculated going forward. This guide assumes that you have existing, active subscriptions. Otherwise, see how to automatically collect tax on new subscriptions or learn more about subscriptions.
Use the following high-level steps to update your active subscriptions to Stripe Tax:
- Activate Stripe Tax if you haven’t already.
- Check customer locations. In some cases, you might need to update the locations.
- Update products and prices with tax codes and tax behaviors.
- Update subscriptions to automatically calculate taxes on future invoices.
- Confirm that you’ve updated the subscriptions correctly.
Activate Stripe Tax
First, you need to activate Stripe Tax. Read the set up guide to learn how.
Check customer locations
To correctly calculate tax, we need to know the customer’s location. After activating Stripe Tax, you can check their tax location status by using the Dashboard, the API, or Dashboard exports.
For more information on which customer address is valid, how they’re used, or how to handle errors, see Collect customer addresses.
Update products and prices
Your products and prices use the default tax behavior you assigned when activating Stripe Tax. If you’d prefer to update active products and prices to calculate tax independently, set a tax_code and tax_behavior. See the full list of available tax codes and the guide for setting up tax codes and tax behavior for more information. For more information about products and prices, including how to decide whether a price should be inclusive or exclusive, see the Tax Setup FAQ.
Update products
First, update any existing products with a tax_
. If you don’t explicitly define a tax_
on your product, Stripe Tax uses the preset product tax code from your settings.
Update prices
Next, update the tax behavior for your prices.
Common mistake
You can’t change tax_
after it’s been set to one of exclusive
or inclusive
. If you want to change the tax behavior of a price, you need to create a new price with the desired behavior, and archive the old price.
Update subscriptions
With your customers, products, and prices updated, you’re ready to update existing subscriptions.
Update subscriptions using Stripe Tax
You can automatically update your existing subscriptions through Stripe Tax.
Get the list of subscriptions that need to be updated from the subscriptions page in the Dashboard. Click Filter, check Automatic tax and select Disabled to display only subscriptions that don’t have automatic tax enabled. Alternatively, you can export all filtered subscriptions to view them as a CSV file. To do this, click Export and select All as the Date range.
How you update the subscriptions depends on their state:
- If your subscriptions don’t have existing tax rates, you only need to enable automatic tax.
- If your subscriptions have existing tax rates (at either the subscription or line-item level), you need to clear out any existing tax rates and enable automatic tax. To avoid creating prorated items, you can schedule this update.
- If your subscriptions have subscriptions schedules, you need to remove instances of
automatic_
in the subscription schedule plans.tax[enabled]=false
Update subscriptions with no existing tax rates
Update subscriptions with existing tax rates
Update Subscriptions with subscription schedules
If you need to collect tax and any of your subscriptions include a subscription schedule that sets automatic_
, you must remove this parameter. To do this, update all phases of the subscription’s schedule by removing automatic_
and setting default_
.
When you update a subscription schedule, you need to pass in all current and future phases. To do this, verify the set parameters, then enable Stripe Tax in the subscription schedule.
To update the subscription schedule after you obtain it, remove the automatic_
parameter, and pass down the other phases and parameters:
Schedule the update
If you want to avoid creating a prorated item, you can schedule the update to occur at the start of the next cycle.
You can currently only schedule subscription updates with the API:
Update subscriptions through Stripe Tax
You can update your subscriptions through Stripe Tax. Updating existing subscriptions ensures that tax is calculated and collected automatically.
You can update subscriptions that meet the following criteria:
- Are active
- Don’t automatically collect tax
- Have sufficient address information to calculate tax
You can’t update subscriptions that are:
- On subscription schedules (refer to this subsection to update subscriptions on subscription schedules)
- Using charge types: Destination charges or Separate charges and transfers
How the process works:
- Removal of manual tax rates: Any existing tax rates on the subscription are removed during the update process.
- Processing time: The update process can take up to 5 business days to complete.
- Completion notification: You receive an email notification after the update is completed.
- Proration: The update doesn’t prorate the tax changes. The updates come into effect from the next billing cycle.
Confirm updates
To confirm that you’ve properly updated your subscriptions, retrieve the upcoming invoice of a subscription and inspect the results of its tax calculation.
You can retrieve the tax amounts from the tax and total_tax_amounts fields on the upcoming invoice, and from the per-line-item tax_amounts fields. The invoice has an automatic_tax field showing the status of the calculation, with one of three possible statuses:
Status | Description | Possible Action |
---|---|---|
complete | Stripe Tax has successfully assessed the taxes on the payment. | You can retrieve the tax amounts from the tax and total_ fields on the latest invoice, and from the per-line item tax_ fields. |
requires_ | Stripe Tax didn’t have enough information to determine the customer’s location and was unable to assess taxes. | Collect more information from a customer (such as a full street address) and update the customer.address field. |
failed | Internal Stripe error. | Try the request again or contact Stripe support for additional assistance. |