Migrate to Stripe Tax

First, you need to activate Stripe Tax. Read the set up guide to learn how.

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.

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.

Update prices

Next, update the tax behavior for your prices.

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. 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_tax[enabled]=false in the subscription schedule plans.

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_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.

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

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

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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:

# 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_4eC39HqLyjWDarjtT1zdp7dc'

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.current_period_start,
        end_date: subscription.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
      }
    ]
  }
)

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.

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: