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.
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 behavior). |
| 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_ 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.
curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -d "line_items[0][price]=sk_test_Hrs6SAopgFPF0bZXSN3f6ELN" \ -d "line_items[0][quantity]=2" \ -d "automatic_tax[enabled]=true" \ -d customer_creation=always \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"{{PRICE_ID}}
Calculate tax for existing customers
To calculate tax on Checkout sessions created for existing customers, set automatic_ to true and specify the customer ID. Checkout uses the following address prioritization 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_toupdate[shipping] autoto add or update the Customer with the collected shipping address.curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -d "line_items[0][price]=sk_test_Hrs6SAopgFPF0bZXSN3f6ELN" \ -d "line_items[0][quantity]=2" \ -d "automatic_tax[enabled]=true" \ -d "customer={{PRICE_ID}}" \ -d "customer_update[shipping]=auto" \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"{{CUSTOMER_ID}}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_toaddress_ collection requiredto always collect a billing address, or leave it atauto(default) to collect when needed. If Checkout collects the billing address, setcustomer_toupdate[address] autoto direct Tax to use the collected billing address, or toneverto use the Customer’s existing address to calculate taxes.curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -d "line_items[0][price]=sk_test_Hrs6SAopgFPF0bZXSN3f6ELN" \ -d "line_items[0][quantity]=2" \ -d "automatic_tax[enabled]=true" \ -d "customer={{PRICE_ID}}" \ -d "customer_update[address]=auto" \ -d billing_address_collection=required \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"{{CUSTOMER_ID}}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.