Collect tax on usage-based rate card subscriptionsPrivate preview
Learn how to calculate and collect tax on usage-based rate card subscriptions.
Private preview
Rate cards are currently in private preview and could change in functionality and integration path before they’re generally available to all Stripe users. Sign up here to join the private preview.
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.
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 informationClient-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:
const stripe = Stripe(
); const elements = stripe.elements({ mode: 'subscription', currency: '{{CURRENCY}}', amount:"pk_test_TYooMQauvdEDq54NiTphI7jx", });{{TOTAL}}
Next, create an Address Element and a Payment Element and mount both:
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.
addressElement.on('change', 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 submissionClient-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.
document.querySelector("#form").addEventListener("submit", 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
(customerDetails); // See the "Create subscription" section below to implement this server-side. const {saveCustomerDetails} = awaitclientSecret(); const { error: confirmError } = await stripe.confirmPayment({ elements, clientSecret, confirmParams: { return_url:createSubscription, }, }); 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. });{{RETURN_URL}}
Save customer detailsServer-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 considerationsUnited 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.
The tax.validate_location enum value helps ensures that the tax location of the customer becomes (or remains) valid as a result of this operation. If it’s not valid, Stripe fails your request with the customer_tax_location_invalid error code. This is important because you can’t create an automatic tax enabled subscription for a customer with an invalid tax location. If you’ve been checking the automatic_tax.status of your preview invoices as advised previously, this additional validation won’t ever fail. However, it’s good practice to set tax[validate_
whenever you’re creating or updating a Customer object.
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.