Update existing subscriptions

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 tax migrations 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.

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’ll need to update the following types of transactions before migrating:

• Transactions with subscription schedules (refer to this subsection to update subscriptions on subscription schedules)
• Transactions with charge types: Destination charges or Separate charges and transfers

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

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.

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

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

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
      }
    ]
  }
)

To confirm that you’ve properly updated your subscriptions, retrieve the upcoming invoice of 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 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: