Automatically collect tax on Checkout sessions

Learn how to automatically calculate taxes in Checkout.

Stripe Tax automatically calculates the taxes on all purchases and subscriptions accumulated during a Checkout session. If you haven’t integrated with Checkout, you must complete the integration using the Accept a Payment guide.

This video shows how to enable automatic tax collection when using hosted integrations like Stripe Checkout.

Loading video content...

Create a Checkout Session

You can create Checkout sessions for one time and recurring purchases.

A customer’s tax rates come from their location, which Checkout assesses from the customer’s address. The address that Checkout uses to calculate taxes depends on whether the customer is new or existing, and whether you collect shipping addresses during the Checkout Session:

	New Customer	Existing Customer
Collect a billing address only	Checkout calculates taxes based on the customer’s billing address entered into the Checkout Session	If the customer has a previously saved shipping address, Checkout calculates taxes based on that address. Otherwise, you can calculate taxes based on billing address entered during Checkout (by specifying customer_update[address]=auto) or the billing address saved to the customer (the default behaviour).
Collect a shipping address	Checkout calculates taxes based on the customer’s shipping address entered into the Checkout Session	Checkout calculates taxes based on the customer’s shipping address entered into the Checkout Session. Existing addresses on the customer won’t apply in this case.

Note

To ensure that Google Pay is offered as a payment method while using Stripe Tax in Checkout, you must either require collecting a shipping address or provide an existing customer with a saved shipping address. Apple Pay with Stripe Tax displays only when the customer’s browser supports Apple Pay version 12 or greater.

Calculate tax for new customers

Set customer_creation=always in the Checkout Session to create a Customer with collected billing and shipping addresses when not identifying an existing customer.

Checkout calculates the tax based on the location of the shipping address, if provided, or else the billing address.

Calculate tax for existing customers

To calculate tax on Checkout sessions created for existing customers, set automatic_tax[enabled] to true and specify the customer ID. Checkout uses the following address prioritisation to calculate taxes:

If specified, Checkout uses the collected shipping address to calculate taxes. If you collect the shipping address, you must also set customer_update[shipping] to auto to add or update the Customer with the collected shipping address.

If you don’t collect the shipping address, Checkout uses the Customer’s existing shipping address to calculate taxes, if available.
If the shipping address isn’t available, Checkout uses the billing address to calculate taxes. Set billing_address_collection to required to always collect a billing address, or leave it at auto (default) to collect when needed. If Checkout collects the billing address, set customer_update[address] to auto to direct Tax to use the collected billing address, or to never to use the Customer’s existing address to calculate taxes.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \ -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2 :" \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d "line_items[0][quantity]"=2 \ -d "automatic_tax[enabled]"=true \ -d customer="{{CUSTOMER_ID}}" \ -d "customer_update[address]"=auto \ -d billing_address_collection=required \ -d mode=payment \ --data-urlencode success_url="https://example.com/success"
Otherwise, Checkout uses addresses from the customer, following the address hierarchy.

Check the response

To inspect the results of the latest tax calculation, you can read the tax amount calculated by Checkout from the total_details.amount_tax on the Checkout Session resource. Additionally, the tax outcome for each payment is available when viewing a payment in the Dashboard.

OptionalUpdate your products and prices

Stripe Tax uses information stored on products and prices to calculate tax, such as tax code and tax behaviuor. If you don’t explicitly specify these configurations, Stripe Tax will use the default tax code selected in Tax Settings.

For more information, see Specify product tax codes and tax behaviour.

OptionalSpecifying tax codes when creating products inline

When creating a Checkout Session with line_items.price_data.product_data, you can specify a tax code directly in the request. We recommend you do this when you’re creating new products rather than using existing product IDs.

Replace txcd_99999999 with the appropriate tax code for your product. The tax code determines how the product is categorised for tax purposes. If you don’t specify a tax code, Stripe Tax uses the default tax code from your Tax Settings.