Tax Rates and Customer Tax IDs make it easier to represent sales and value-added-tax on invoices.

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 tax-percent of 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 tax_percent to 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 tax_percents.

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.

As your Tax Rates lack a display_name and jurisdiction, tax reporting may not be very useful. Invoices and receipts will render a generic name for these rates—“Tax”.

2. Minimal update with medium benefits

Use the dashboard to edit pre-existing tax rates so taxes work for pre-existing invoices.

1. 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.
2. 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

We recommend no longer using the tax_percent field for new invoices, and start using Tax Rates instead. Apply Tax Rates to invoices and subscriptions.

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

The Customer’s tax_info, tax_info_verification, and business_vat_id fields have been deprecated in favor of the new tax_ids field, and will be removed in future versions.

The Customer API’s tax_info and business_vat_id params, on the create and update methods, have been deprecated in favor of the new Tax ID API, 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, e.g. a “German EU VAT” number.

See the Customer Tax IDs page for more information.