Automatically collect tax with the Checkout page

Learn how to automatically calculate taxes in Checkout using the Stripe-hosted page or full embedded page.

This guide shows you how to calculate and verify tax for new and existing customers through the Stripe-hosted payment page or Embedded payment page. If you haven’t integrated with Stripe Checkout, start with the Accept a Payment guide first.

Join the preview for automatic tax calculation in Checkout.

Request to join the preview for no code automatic tax calculation. Available only for one-time payments processed through Stripe Checkout.

Loading video content...

Add tax registrations Dashboard Server-side

Stripe Tax only collects tax in jurisdictions where you have an active registration. Create a registration for each country or state where you’re required to collect tax. The country_options structure varies by country.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Alternatively, add registrations in the Dashboard. Go to the Tax > Registrations. You only need to add a registration once per jurisdiction.

Create a Checkout Session Server-side

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 it’s a new or existing customer, and whether you collect a shipping address in the Checkout Session.

Use automatic tax with any payment method

Setting automatic_tax.enabled to true applies automatic tax to the entire Checkout Session. You don’t need to enable automatic tax separately for cards, stablecoins or other eligible payment methods. The selected payment method doesn’t change the inputs that Stripe Tax uses: your Tax settings and registrations, the product tax code and price tax behaviour, the Checkout Session’s taxable amount and the customer location that Checkout resolves using the address hierarchy above.

Payment methods provide different location information. Checkout reuses an existing customer address or collects a shipping or billing address according to the hierarchy above. If Checkout needs additional location information to calculate tax, it collects the required billing details.

For example, when a customer pays with stablecoins, Checkout calculates tax using the Checkout Session’s amount and presentment currency before authorising payment. The stablecoin token, wallet and network that the customer selects – and the subsequent settlement to your Stripe balance – don’t trigger another Stripe Tax calculation or require crypto-specific Stripe Tax configuration. The tax calculation still depends on your registrations, the customer’s location, the product classification and the rules that apply in the relevant jurisdiction.

Google Pay in Checkout

To make sure Google Pay is offered as a payment method while using Stripe Tax in Checkout, you must either collect a shipping address or provide an existing customer with a saved shipping address.

Calculate tax for new customers

Set customer_creation=always in the Checkout Session to create a customer-configured Account or Customer with their billing and shipping addresses. Checkout calculates taxes based on the shipping address (if provided) or the billing address if no shipping address has been provided.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Calculate tax for existing customers

To calculate tax on Checkout Sessions for existing customer-configured Accounts, set automatic_tax.enabled to true and customer_account to the Account ID. Checkout uses the following address prioritisation to calculate taxes:

1. 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 the collected shipping address to the Account, or update the Account ’s existing shipping address. 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_Ou1w6LVt3zmVipDVJsvMeQsc:" \ -d "line_items[0][price]={{the related setting}}" \ -d "line_items[0][quantity]=2" \ -d "automatic_tax[enabled]=true" \ -d "customer_account={{the related setting}}" \ -d "customer_update[shipping]=auto" \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"
2. If you don’t collect the shipping address, Checkout uses the Account ’s existing shipping address to calculate taxes, if available.
3. 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 auto (default) to collect it when needed. If Checkout collects the billing address, set customer_update.address to auto to calculate taxes using the collected billing address, or to never to use the Account ’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_Ou1w6LVt3zmVipDVJsvMeQsc:" \ -d "line_items[0][price]={{the related setting}}" \ -d "line_items[0][quantity]=2" \ -d "automatic_tax[enabled]=true" \ -d "customer_account={{the related setting}}" \ -d "customer_update[address]=auto" \ -d billing_address_collection=required \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success"
4. Otherwise, Checkout uses addresses from the Account, following the address hierarchy.

Check the response Server-side

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. You can also see the tax outcome for each payment when viewing a payment in the Dashboard.

Optional Update your products and prices

Optional Specify tax codes with inline products Server-side

See also

• Test your tax integration
• Determine customer locations
• Reporting and filing