Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Overview
Fraud detection
Stripe data
Financial reports
Payment authentication reports
Revenue recognition
Startup incorporation
Climate
Identity
Tax
    Overview
    Getting Started
    Set up
    Configure your tax settings
    Select tax categories
    Monitor your tax obligations
    Add a tax registration
    Tax registration rules by location
    Integrating
    Set tax categories, products, and prices
    Payment Links and Tax
    Checkout and Tax
      Checkout and tax IDs
    Invoicing and Tax
    Billing and Tax
    Custom Payments Flows and Tax
    Manage your integration
    How tax is calculated
    Sales Tax Holidays
    Account and customer tax IDs
    Address validation
    Zero tax amounts and reverse charges
    Tax compliance
    End-to-end tax compliance
    Reporting
    Filing and Remittance
    Frequently asked questions
Financial Connections
Account
Dashboard
Tax
·
HomeBusiness operationsTax

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.

Log in or sign up for Stripe to activate Stripe Tax.

Update your products and prices

Stripe Tax uses information stored on the Products and Prices APIs to determine the right rates and rules to apply when calculating tax. Update the products and prices you use to include:

  1. Tax behavior: The tax behavior on a price can be either inclusive or exclusive. This determines how the buyer sees the tax. When you set tax behavior to exclusive, it adds tax onto the subtotal amount you specify on your price. This is common in US markets and for B2B sales. When set to inclusive, the amount your buyer pays never changes, even if the tax rate varies. This is common practice for B2C buyers in many markets outside the US.
  2. (Optional) Tax category: a tax category is a classification of your product or service for Stripe Tax. We use this to make sure that we apply the correct tax rate to your transactions. Some examples include “Audio book”, “Gift card”, or “Software as a service”. If you don’t set this, Stripe Tax uses the default tax category set in tax settings.

You can’t change tax_behavior after you set it to one of “exclusive” or “inclusive.” You can create a new price and archive the current one instead.

If you don’t want to create your products and prices upfront, you can pass price_data.tax_behavior and product_data.tax_code when creating Checkout sessions.

Learn more about Products, prices, tax codes, and tax behavior.

Create a Checkout Session

After updating your products and prices, you’re ready to start calculating tax on your Checkout sessions. You can create sessions for one time and recurring purchases.

Refunds of charges associated with a Checkout session don’t reduce your overall tax liability and don’t show up in Stripe Tax reporting.

For recurring payments, use credit notes instead of refunds. Credit notes reduce your overall tax liability and show up in Stripe Tax reporting. Learn more about how credit notes work.

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’re collecting shipping addresses during the Checkout Session:

New CustomerExisting Customer
Collecting a billing address onlyCheckout calculates taxes based on the customer’s billing address entered into the Checkout SessionIf the customer has a previously saved shipping address, Checkout calculates taxes based on that address. Otherwise, you can choose to 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).
Collecting a shipping addressCheckout calculates taxes based on the customer’s shipping address entered into the Checkout SessionCheckout 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.

When you enable Stripe Tax in Checkout, Google Pay is only available to customers for sessions that require collecting a shipping address. Apple Pay with Stripe Tax displays only when the customer’s browser supports Apple Pay version 12.

Calculating tax for new customers

If you don’t pass in an existing customer when creating a Checkout session, Checkout creates a new customer and automatically saves billing address and shipping information. For tax collection purposes, Checkout uses billing and shipping addresses to determine the customer’s location.

Checkout uses the shipping address entered during the session to determine the customer’s location for calculating tax. If you don’t collect shipping information, Checkout uses the billing address.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "line_items[0][price]"=price_H5ggYwtDq4fbrJ \ -d "line_items[0][quantity]"=2 \ -d "automatic_tax[enabled]"="true" \ -d mode=payment \ -d success_url="https://example.com/success" \ -d cancel_url="https://example.com/cancel"

Calculating tax for existing customers
Optional

To calculate tax on Checkout sessions created for existing customers, you can set the automatic_tax[enabled] parameter to true when creating the session. You can choose to either base tax calculations on the customer’s existing addresses or new addresses collected during the session:

Use existing addresses on the customer for taxes

If you’ve already collected the addresses of existing customers, you can choose to base tax calculations on those addresses rather than the addresses collected during checkout:

  • Which customer address does Checkout use for taxes?

    If available, Checkout uses the customer’s saved shipping address to calculate taxes. Otherwise, Checkout uses the customer’s saved billing address to calculate taxes.

  • Do the customer addresses have to meet any requirements?

    When using existing addresses for taxes, the customer must either have a valid shipping address or billing address saved. You can see whether or not a customer’s saved addresses are valid by checking the customer’s customer.tax.automatic_tax property. If the property is supported or not_collecting, it means the customer’s saved address are valid, and you can enable Stripe Tax on Checkout sessions for that customer.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "line_items[0][price]"=price_H5ggYwtDq4fbrJ \ -d "line_items[0][quantity]"=2 \ -d "automatic_tax[enabled]"="true" \ -d "customer"="cus_HQmikpKnGHkNwW" \ -d mode=payment \ -d success_url="https://example.com/success" \ -d cancel_url="https://example.com/cancel"

You can’t use existing addresses on the customer for taxes when collecting a shipping address during checkout. If you’re collecting shipping addresses during checkout, you must use the addresses entered during checkout for taxes.

Use addresses collected during Checkout for taxes

You can configure Checkout to save new billing or shipping addresses to a customer. In this case, Checkout calculates tax using the address entered during checkout.

  • Which address does Checkout use for taxes?

    If you’re collecting shipping addresses, Checkout uses the shipping address entered during the session to calculate taxes. Otherwise, Checkout uses the billing address entered during the session to calculate taxes.

  • Where are the addresses collected during Checkout saved?

    If you’re collecting shipping addresses, Checkout saves the shipping address entered during the session to the customer’s customer.shipping.address property. Otherwise, Checkout saves the billing address entered during the session to the customer’s customer.address property. In both cases, the address used for taxes overrides any existing addresses.

If you’re collecting shipping addresses with Checkout, set the customer_update[shipping] property to auto so that you copy the shipping information from Checkout to the customer.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "line_items[0][price]"=price_H5ggYwtDq4fbrJ \ -d "line_items[0][quantity]"=2 \ -d "automatic_tax[enabled]"="true" \ -d "customer"="cus_HQmikpKnGHkNwW" \ -d "customer_update[shipping]"="auto" \ -d "shipping_address_collection[allowed_countries][0]"="US" \ -d mode=payment \ -d success_url="https://example.com/success" \ -d cancel_url="https://example.com/cancel"

If you aren’t collecting shipping addresses with Checkout, and you want to use billing addresses entered during checkout for taxes, you must save the billing address to the customer. Set the customer_update[address] property to auto so that you copy the newly-entered address onto the provided customer.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "line_items[0][price]"=price_H5ggYwtDq4fbrJ \ -d "line_items[0][quantity]"=2 \ -d "automatic_tax[enabled]"="true" \ -d "customer"="cus_HQmikpKnGHkNwW" \ -d "customer_update[address]"="auto" \ -d mode=payment \ -d success_url="https://example.com/success" \ -d cancel_url="https://example.com/cancel"

Check the response
Optional

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.

See also

  • Determining customer locations
  • Checkout and tax IDs
  • Reporting and filing
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Update your products and prices
Create a Checkout Session
Calculating tax for new customers
Calculating tax for existing customers
Check the response
See also
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$