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.

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', 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", 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.

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.

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_location]="immediately" 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.

Go to the Rate cards page and click the rate card you want to subscribe your customer to.
In the rate card details page, click the overflow menu () next to Edit rate card.
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.