Update existing subscriptions
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.
Interested in using Stripe Tax and currency conversion?
We’re developing a Payment Element integration that manages tax, discounts, shipping, and currency conversion. Read the Build a checkout page guide to learn more.
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_code
. If you don’t explicitly define a tax_code
on your product, Stripe Tax uses the preset product tax code from your settings.
Here’s how to update a Product with a tax_code
using the API:
To update a Product with a tax_code
in the Dashboard, go to the Products page, select a product to edit and, in the product information page, choose the tax code from the drop-down menu.
Update prices
Next, update the tax behavior for your prices.
Common mistake
You can’t change tax_behavior
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.
Here’s how to update a price with the API:
To update a price with the Dashboard, go to the products page, select the product with the price you want to update, and select additional options in the price information section. In the Include tax in price drop-down menu, select the behavior you want to associate with the price.
Update subscriptions
With your customers, products, and prices updated, you’re ready to update existing subscriptions.
Caution
Stripe Tax requires a recognized customer location to calculate tax for a subscription. Therefore, an invoice for a subscription with automatic_tax[enabled]=true
can’t be finalized when the customer’s location is unrecognized. Payment can’t be collected if the invoice can’t be finalized. Read more about the behavior of subscriptions when the customer’s location is unrecognized.
To get a list of subscriptions that need to be updated, go to the subscriptions page, click Export, select All as the Date range, and select All columns in the Columns drop-down menu. Then you can filter by Automatic Tax Enabled column in the CSV export.
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_tax[enabled]=false
in the subscription schedule plans.
Update subscriptions with no existing tax rates
To update subscriptions that have no tax rates configured, set automatic_tax.enabled
to true
.
Setting automatic_tax.enabled=true
activates automatic tax calculations for all subsequent invoices created for that subscription.
To do this through the Dashboard, update the subscription and turn on the Calculate tax automatically option.
Update subscriptions with existing tax rates
To update subscriptions with tax rates set at the subscription level, you need to remove the tax rates before enabling automatic_tax
. When you make the update:
- Pass an empty string in the
default_tax_rates
andtax_rates
fields for each subscriptionitem
. Doing this clears out tax rates set at both the subscription (default_tax_rates
) and line-item (tax_rates
) levels. - Set
automatic_tax.enabled
totrue
.
To make this update through the Dashboard, edit the subscription, then enable the calculate tax automatically option. The Dashboard automatically calculates tax going forward and removes any existing tax rates. If you haven’t updated your prices to set tax_behavior
, the Dashboard prompts you to update any missing details before you can update the subscription.
Update Subscriptions with subscription schedules
If you need to collect tax and any of your subscriptions include a subscription schedule that sets automatic_tax[enabled]=false
, you must remove this parameter. To do this, update all phases of the subscription’s schedule by removing automatic_tax[enabled]=false
and setting default_settings[automatic_tax][enabled]=true
.
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_tax[enabled]=false
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:
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_tax_amounts fields on the latest invoice, and from the per-line item tax_amounts fields. |
requires_location_inputs | 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. |