This guide explains how to migrate from
tax_percent to Tax Rates, and
business_vat_id to Customer Tax IDs.
Upgrade your integration to use these new objects for better tax collection and reporting (remittance) tools.
Moving from tax percent to Tax Rate
The new Tax Rate object allows you to better represent tax rates. This improves rendering on invoices and tax reporting.
Existing tax percent use cases have been migrated to tax rates
Your existing tax_percent uses have already been automatically converted into Tax Rate objects for you, and your Invoices and Subscriptions have been updated to reference the new objects via the default_tax_rates field.
This means that if you had previously been setting a
15% on your invoices, Stripe has created a new
15% Tax Rate object for you (although it lacks details such as a customer facing display name or a jurisdiction).
If you continue to set the
15%, Stripe dynamically creates a 15% Tax Rate for you to aid your migration. This will continue to work exactly as it had before.
You can browse your full list of Tax Rates on the Dashboard’s Tax Rates page, where you can easily manage them.
The new API is much more expressive. If you use multiple tax rates, inclusive tax rates, or set them at the item level,
tax_percent will be rendered null.
Upgrade path: Pick from 3 levels of implementation effort
For new invoices or subscriptions, we recommend performing the full suite of updates if you can. This is a very small amount of work if you’re currently using a handful of
However, there are a few possible paths to take.
1. No action
If you take no action, your integration will continue to work as it does today. As mentioned above, existing uses of
tax_percent are made to look as if they used Tax Rates.
2. Minimal update with medium benefits
Use the dashboard to edit pre-existing tax rates so taxes work for pre-existing invoices.
- For Tax Rates that have been migrated for you, edit the display_name to have a useful user-facing name. Display names are displayed to your customers on generated invoices and receipts. For example, “UST” for German VAT, and “HST” for Ontario’s Harmonized Sales Tax.
- Similarly, set the jurisdiction to store an associated tax jurisdiction that is meaningful to you. For example, “DE” for Germany or “NL Amsterdam” for the city of Amsterdam.
Invoices and receipts show the
display_name of tax rates. When determining how much tax to remit, you’re able to group by jurisdiction.
3. Full update and benefits
This allows you to add multiple tax rates per line item and invoice, display the correct name for tax rates and summaries on generated invoices and receipts, and improved tax reporting.
Moving from tax info to Customer Tax IDs
business_vat_id fields have been deprecated in favor of the new tax_ids field, and will be removed in future versions.
The new Tax ID object provides:
- Multiple tax IDs on a Customer.
- Support for more tax ID types, such as EU VAT, NZ GST, AU ABN.
- Automatic validation of EU VAT numbers against the European Commission’s VAT Information Exchange System (VIES) database.
- Automatic validation of Australian Business Numbers (ABNs) against the Australian Business Register (ABR).
- Associate a country with a tax ID, for example, a “German EU VAT” number.
See the Customer Tax IDs page for more information.