Private preview

Collect tax on usage-based rate card subscriptions Private preview

Learn how to calculate and collect tax on usage-based rate card subscriptions.

Note

This page describes basic usage-based billing with Billing Meters. Unless you’re maintaining an existing Billing Meters integration, use Metronome, which handles metering, pricing models, prepaid credits, enterprise contracts, and automated invoice generation. Compare your options to decide which approach fits your use case.

You can use Stripe Tax to calculate the tax amount on recurring payments for rate card subscriptions. To automatically handle tax calculation when your customer is ready to pay, set the customer’s location details when you create a rate card subscription.

Activate Stripe Tax

Log in or sign up for Stripe to activate Stripe Tax.

Update rate cards (optional)

When you create a rate card, you specify the product tax code. If you don’t specify a code, Stripe Tax uses the default tax code selected in your Tax Settings.

Collect customer information Client-side

After you have an estimate of the taxes and the total, you can collect customer information, including:

• Shipping address (if applicable)
• Billing address
• Payment details

Stripe Tax collects payment details without creating a Setup Intent. The first step is to create an Elements object without an Intent:

checkout.js

const stripe = Stripe("pk_test_TYooMQauvdEDq54NiTphI7jx");

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');

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

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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.

Subscribe your customer to a rate card

After you create a rate card, you can start subscribing customers.

When you subscribe your customer to the rate card, you also define the billing cadence–how often to create invoices for your customer. You specify how to collect when you create a billing cadence: either charge automatically or send an invoice. If you charge automatically, an invoice is created and the customer’s default payment method is charged. If you send an invoice, customers receive an invoice they need to pay manually.

1. Go to the Rate cards page and click the rate card you want to subscribe your customer to.
2. In the rate card details page, click the overflow menu ( ) next to Edit rate card .
3. In the rate card subscription editor:

• Find or add a customer.
• Define the Billing cadence , which is how often to and when to invoice the customer.
• Click Collect tax automatically with Stripe Tax to enable automatic Tax collection with Stripe Tax.
• Click Create subscription .