Collect taxes

Use Stripe Tax to calculate and collect taxes in your custom integration with Elements.

Use Stripe Tax to automatically calculate the tax on your transactions without requiring you to define the rates and rules. Fees only apply after you add at least one location where you’re registered to calculate and remit tax.

Configure your Checkout Session to collect tax

To start collecting tax:

Pass automatic_tax[enabled]=true when creating a Checkout Session.
Specify a tax_code for each line item, or set a preset tax code in the Dashboard.
Specify a tax_behavior for each line item, or set a default tax behavior in the Dashboard.

This code enables automatic tax calculation using Stripe Tax, a tax code, and a tax behavior. Stripe Tax then uses the tax code and tax behavior to automatically calculate taxes.

Tax codes

The tax codes associate products with tax rates. Choose the appropriate tax code for your product from the list of tax codes. If a product doesn’t match with any of the tax codes, you can use one of the General codes.

Tax behavior

The tax behavior determines how to present tax to the customer:

Exclusive: The product price doesn’t include tax, which is added as a separate amount.
Inclusive: The product price includes any tax amount.

OptionalCollect tax through the Payment Element

You can collect tax address details directly in the Payment Element. Collecting tax address details through the Payment Element is suitable for the following use cases:

You don’t require full address collection.
You only require address collection for tax collection purposes.

This feature integrates input fields for the country and postal code into each payment method form within the Payment Element. It only collects the minimum required address fields for tax calculation based on Stripe Tax requirements.

There are certain regional considerations where the tax rate using the minimum required address fields might differ from the tax rate at your customer’s full address. We recommend using the Address Element to collect your customer’s full address for tax calculation if these regional considerations apply to your business.

When you create the Checkout Session, set billing_address_collection=auto to automatically collect the billing address.

Don’t include the shipping_address_collection parameter. If you provide this parameter, tax address details are collected based on the shipping address instead of the billing address.

When collecting tax address details through the Payment Element, tax calculation behaves as follows for the following scenarios:

If you pass fields.billingDetails.address=auto | if_required, the Payment Element collects the minimum required address fields for tax calculation.
If you pass fields.billingDetails.address=never, you must collect tax address details through an alternative method because the billing input fields won’t show in the Payment Element.
If you pass fields.billingDetails.address.country=never, the customer’s detected country is used for tax calculation.
If you pass fields.billingDetails.address.postalCode=never, the method returns an error because the postal code might be required for certain countries.
If you call checkout.updateBillingAddress, the method returns an error because the billing address could potentially conflict.

OptionalCheck the response

You can view the calculated tax amount for each payment as follows:

In the Checkout Session resource, review the total_details.amount_tax property.
In the Dashboard, review the tax outcome for each payment.

Render the tax amount

Use the useCheckout hook to display the tax amount in your payment form.

import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const checkoutState = useCheckout();
  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  } else if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }
  const {checkout} = checkoutState;
  return (
    <div>
      <h2>Checkout Summary</h2>
      <pre>
        {JSON.stringify(checkout.lineItems, null, 2)}
      </pre>
      <h3>Totals</h3>
      <pre>
        Subtotal: {checkout.total.subtotal.amount}
        {/* Make sure you use the appropriate tax amount type (taxInclusive and/or taxExclusive) for your integration */}
        Tax: {checkout.total.taxExclusive.amount}
        Total: {checkout.total.total.amount}
      </pre>
    </div>
  )
};