Collect taxes for recurring payments

Stripe Tax uses information stored on products and prices to calculate tax, such as tax code and tax behavior.

See Specify product tax codes and tax behaviour to learn more.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

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:

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:

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.

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...
});

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 
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.
});

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.

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.

curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

The tax.validate_location enum value helps you make sure that the tax location of the customer becomes (or remains) valid as a result of this operation. If not, 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.

Create a subscription with automatic tax enabled.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.payment_intent"

The latest_invoice.payment_intent.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.

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.