Skip to content
Create account or Sign in
/Ask AI
Create accountSign in
APIs & SDKsHelp
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
Tax
Overview
Reporting
OverviewReports for multiple accounts
Data
OverviewNext generation of Data PipelineDatabase
Canada
English (United States)

Collect taxes for recurring payments

Learn how to collect and report taxes for recurring payments.

To calculate tax for recurring payments, Stripe offers Stripe Tax and tax rates:

  • Stripe Tax—A paid product that automatically calculates the tax on your transactions without the need to define the rates and rules. Fees only apply after you’ve added at least one location where you’re registered to calculate and remit tax. For more information, see Stripe Tax. If you use a third-party tax provider such as Avalara, Anrok, or Sphere, you can connect them natively using a third-party tax app.

  • Tax rates—A free feature for manually defining a fixed set of tax rates on invoices, subscriptions, and one-time payments that use Checkout. Stripe won’t create or maintain any tax rates on your behalf. If you use a third-party tax provider such as Avalara, Anrok, or Sphere, use their native Stripe integration to calculate tax automatically for subscriptions and invoices. Use tax rates if you have a fixed set of rates or use a provider without a native integration. For more information, see Tax Rates and how to use them.

Stripe Tax allows you to calculate the tax amount on your recurring payments when using Stripe Billing. Use your customer’s location details to preview the tax amount before creating a subscription and then create it with Stripe Tax enabled when your customer is ready to pay. Stripe Tax integrates with Stripe Billing and automatically handles tax calculation with your pricing model, prorations, discounts, trials, and so on.

This guide assumes you’re setting up Stripe Tax and Billing for the first time. See how to update existing subscriptions.

If you’re using Stripe Checkout to create new subscriptions, see how to automatically collect tax on Checkout sessions, or watch the short video below:

Loading video content...

Estimate taxes and total
Server-side

When a customer first enters your checkout flow, you might not have their address information yet. In this case, create a preview invoice and set customer_details.tax.ip_address to let Stripe locate them using their IP address.

Caution

In most cases, Stripe can resolve an IP address to a physical area, but its precision varies and might not reflect your customer’s actual location. We don’t recommend relying on a customer’s IP address to determine their address beyond an initial estimate.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "automatic_tax[enabled]=true" \
  -d "customer_details[tax][ip_address]={{IP_ADDRESS}}" \
  -d "subscription_details[items][0][price]=
{{PRICE_ID}}
"

Check the automatic_tax.status of the invoice. If the status is requires_location_inputs, it means that the address details are invalid or insufficient. In this case, prompt your customer to re-enter their address details or provide accurate address details.

The invoice total is how much your customer pays and tax is the sum of all tax amounts on the invoice. If you want a breakdown of taxes, see total_tax_amounts. All amounts are in cents.

Zero tax

If the tax is zero, make sure that you have a tax registration in your customer’s location. See how to register for sales tax, VAT, and GST and learn more about zero tax amounts and reverse charges.

Collect customer information
Client-side

After you have an estimate of the taxes and the total, start collecting customer information including their shipping address (if applicable), billing address, and their payment details. Notice that when you use Stripe Tax, you collect payment details without an Intent. The first step is to create an Elements object without an Intent:

checkout.js
const stripe = Stripe(
"pk_test_A7jK4iCYHL045qgjjfzAfPxu"
);

const elements = stripe.elements({
  mode: 'subscription',
  currency: '{{CURRENCY}}',
  amount: 
{{TOTAL}}
,
});

Next, create an Address Element and a Payment Element and mount both:

checkout.js
const addressElement = elements.create('address', {
  mode: 'billing' // or 'shipping', if you are shipping goods
});
addressElement.mount('#address-element');

const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Then you can listen to change events on the Address Element. When the address changes, re-estimate the taxes and the total.

checkout.js
addressElement.on('change', async function(event) {
  // Throttle your requests to avoid overloading your server or hitting
  // Stripe's rate limits.
  const { tax, total } = await updateEstimate(event.value.address);

  elements.update({ amount: total });
  // Update your page to display the new tax and total to the user...
});

Common mistake

When your customer is entering their address, Address Element fires a change event for each keystroke. To avoid overloading your server and hitting Stripe’s rate limits, wait for some time after the last change event before re-estimating the taxes and the total.

Handle submission
Client-side

When your customer submits the form, call elements.submit() to validate the form fields and collect any data required for wallets. You must wait for this function’s promise to resolve before performing any other operations.

checkout.js
document.querySelector("#form").addEventListener("submit", async function(event) {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  const { error: submitError } = await elements.submit();
  if (submitError) {
    // Handle error...
    return;
  }

  const { value: customerDetails } = await addressElement.getValue();

  // See the "Save customer details" section below to implement this
  // server-side.
  await 
saveCustomerDetails
(customerDetails);

  // See the "Create subscription" section below to implement this server-side.
  const { 
clientSecret
 } = await 
createSubscription
();

  const { error: confirmError } = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 
{{RETURN_URL}}
,
    },
  });
  if (confirmError) {
    // Handle error...
    return;
  }

  // Upon a successful confirmation, your user will be redirected to the
  // return_url you provide before the Promise ever resolves.
});

Save customer details
Server-side

Update your Customer object using the details you’ve collected from your customer, so that Stripe Tax can determine their precise location for accurate results.

Regional considerations
United States

If your customer is in the United States, provide a full address if possible. We use the term “rooftop-accurate” to mean that we can attribute your customer’s location to a specific house or building. This provides greater accuracy, where two houses located side-by-side on the same street might be subject to different tax rates, because of complex jurisdiction boundaries.

If you haven’t already created a Customer object (for example, when your customer first signs up on your website), you can create one now.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
 \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "address[line1]={{LINE1}}" \
  -d "address[line2]={{LINE2}}" \
  -d "address[city]={{CITY}}" \
  -d "address[state]={{STATE}}" \
  -d "address[postal_code]={{POSTAL_CODE}}" \
  -d "address[country]={{COUNTRY}}" \
  -d "tax[validate_location]=immediately"

Caution

If your customer has other existing subscriptions with automatic tax enabled and you update their address information, the tax and total amounts on their future invoices might be different. This is because tax rates vary depending on customer location.

Your customer must have a valid tax location in order to enable automatic tax on their subscription. Set tax.validate_location to immediately to validate the customer’s tax location. If validation fails, Stripe fails your request with the customer_tax_location_invalid error code. Checking the automatic_tax.status of your preview invoices helps avoid this failure.

Create subscription
Server-side

Create a subscription with automatic tax enabled.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "automatic_tax[enabled]=true" \
  -d "customer=
{{CUSTOMER_ID}}
" \
  -d "items[0][price]=
{{PRICE_ID}}
" \
  -d "payment_settings[save_default_payment_method]=on_subscription" \
  -d "expand[0]=latest_invoice.confirmation_secret"

The latest_invoice.confirmation_secret.client_secret is the client secret of the payment intent of the first (and the latest) invoice of the new subscription. You need to pass the client secret to your front end to be able to confirm the payment intent.

Security tip

Don’t store, log, or expose the client secret to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.

If your customer has a default payment method, the first invoice of the subscription is paid automatically. You can confirm this using latest_invoice.status of the subscription. If you want to use the new payment details you collected from your customer in your checkout flow, make sure that the first invoice isn’t paid automatically. Pass default_incomplete for the payment_behavior when you’re creating your subscription and confirm the payment intent using stripe.confirmPayment() as shown. See Billing collection methods for more information.

OptionalUpdate your products and prices

OptionalHandle refunds
Server-side

Use webhooks

We recommend listening to subscription events with webhooks because most subscription activity happens asynchronously.

When you start using Stripe Tax, make sure to listen to invoice.finalization_failed events. If the automatic_tax.status of the invoice is requires_location_inputs, it means that the address details of your customer are invalid or insufficient. In this case, Stripe can’t calculate the taxes, can’t finalize the invoice, and can’t collect the payment. Notify your customer to re-enter their address details or provide an accurate address.

See Using webhooks with subscriptions to learn more.

See also

Morty Proxy This is a proxified and sanitized view of the page, visit original site.