Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
Tax
    Overview
    Get started
    How Tax works
    Set up
    Using the Settings API
    Testing
    Integrate by payment flow
    Payment Links
    Checkout
    Invoicing
    Subscriptions
      Update existing subscriptions
    Rate card subscriptions
    Custom payment integration
    Integrate with Stripe Connect
    Overview
    Tax for software platforms
    Tax for marketplaces
    Manage your compliance
    Monitor your obligations
    Register
    Calculate tax
    Report
    Third-Party Tax Apps
    File and Remit
    Tax Reference
    Product tax codes
    Supported countries
    FAQ
Reporting
Data
Startup incorporation
HomeFinance automationTaxSubscriptions

Update existing subscriptions

Learn how to update existing subscriptions to Stripe Tax.

Copy page

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. Stripe provides tooling to help you update your subscriptions. You can also manually update subscriptions where you want more control over certain options.

Update existing subscriptions using automated tooling

First, you need to activate Stripe Tax. To learn how, read the setup guide.

To use the tooling, follow these steps:

  1. Go to the Dashboard.
  2. Review the subscriptions you need to update.
  3. Review the recommended actions.
  4. Make any necessary manual updates.

Stripe removes manual tax rates from the subscriptions, which can take up to 5 business days. When the process is complete, we notify you by email.

Note

We don’t prorate the tax changes. The updates take effect at the start of the next billing cycle.

You can use the tooling to update subscriptions that meet the following criteria:

  • Are active
  • Don’t automatically collect tax
  • Have sufficient address information to calculate tax

You need to update the following types of subscriptions:

  • Subscriptions with schedules. To learn more, see the Update Subscriptions with subscription schedules section.
  • Subscriptions that use the charge types destination charges or separate charges and transfers.

Update existing subscriptions manually

  • Review customer locations and make any required updates.
  • 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.

Check customer locations

To correctly calculate tax, we need to know the customer’s tax location status. You can check it in the Dashboard or in exported data, or get the information using the API.

To check a customer’s tax location status through the Dashboard, go to the Customers page, select the customer, and expand their details. The tax location status (automatic_tax) has four possible values:

StatusDescriptionPossible Action
Valid (supported)Automatic tax fully supported.No further action required.
Unrecognized location (unrecognized_location)The address isn’t valid for determining a tax location.Ask the customer for an updated address and set customer.address to the new value. You can update the value through the API or Dashboard by editing the customer’s details.
Not registered (not_collecting)The address is recognized and resolved to a location that you haven’t set up a collection location for.The action to take depends on your tax obligations. If you proceed, Stripe Tax doesn’t assess any taxes. If you want it to assess tax, add an active registration for the jurisdiction the customer is based in.
failedAn error occurred with Stripe’s servers. This is rare.Try the request again or contact Stripe support for additional assistance.

In case the status=unrecognized_location you need to update the customer location with an address that Stripe Tax can use. In the Dashboard, you can go into the Customers page, select the customer, and change its billing or shipping address under Details.

Check tax location status through exports

To check the tax location status of your customers through Dashboard exports, go to the Customers page, click Export, and select All columns.

The CSV file includes a Boolean column named Tax Location Recognized that you can use to determine whether a customer has a valid address.

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.

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.

To update a price using the Dashboard:

  1. Go to the products page.
  2. Select the product with the price you want to update.
  3. Select additional options in the price information section.
  4. 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.

Get the list of subscriptions that need to be updated from the subscriptions page in the Dashboard. To display only subscriptions that don’t have automatic tax enabled, click Filter, check Automatic tax, and select Disabled. 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_tax[enabled]=false in the subscription schedule plans.

Update subscriptions with no existing tax rates

To update subscriptions with no existing tax rates using 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 through the Dashboard, edit the subscription, then enable the calculate tax automatically option. The Dashboard removes any existing tax rates and automatically calculates tax going forward. 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 that parameter. To do so, 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.

Command Line
cURL
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

To update the subscription schedule after you obtain it, remove the automatic_tax[enabled]=false parameter, and pass down the other phases and parameters:

Command Line
cURL
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "phases[0][items][0][price]"=price_1GqNdGAJVYItwOKqEHb \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][start_date]"=1577865600 \ -d "phases[0][end_date]"=1578038400 \ -d "phases[1][items][0][price]"=price_1GqNdGAJVYItwOKqEHb \ -d "phases[1][items][0][quantity]"=2 \ -d "phases[1][start_date]"=1578038400 \ -d "phases[1][end_date]"=1580544000 \ -d "default_settings[automatic_tax][enabled]"=true

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:

server.rb
Ruby
# Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
subscription = Stripe::Subscription.retrieve( '{{SUBSCRIPTION_ID}}', ) schedule = Stripe::SubscriptionSchedule.create({ from_subscription: subscription.id }) Stripe::SubscriptionSchedule.update( schedule.id, { end_behavior: 'release', phases: [ # The first phase contains items for the # latest subscription invoice { items: [ # Prices and tax_rates for each item { price: '{{PRICE_ID}}', tax_rates: [ '{{TAX_RATE_ID}}' ] } ], default_tax_rates: ['{{TAX_RATE_ID}}'], start_date: subscription.items.data[0].current_period_start, end_date: subscription.items.data[0].current_period_end }, # The second phase removes manual tax rates and enables # automatic tax calculation { items: [ # Prices for each item with tax_rates: '' { price: '{{PRICE_ID}}', tax_rates: '' } ], default_tax_rates: '', automatic_tax: {enabled: true}, iterations: 1 } ] } )

Confirm updates

To confirm that you’ve properly updated your subscriptions, create a preview invoice for each 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 preview 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:

StatusDescriptionPossible Action
completeStripe 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_inputsStripe Tax was unable to assess taxes because it didn’t have enough information to determine the customer’s location.Collect more information from a customer (such as a full street address) and update the customer.address field.
failedInternal Stripe error.Try the request again or contact Stripe support for additional assistance.

See also

  • Create new subscriptions with Stripe Tax
  • Setting tax codes, products, and prices
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc