Automatically collect tax on Checkout sessions
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.
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:
- 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.
- (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. Learn more about how refunds work.
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 Customer | Existing Customer | |
|---|---|---|
| Collecting 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 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 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. |
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.
Calculating tax for existing customersOptional
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_taxproperty. If the property issupportedornot_collecting, it means the customer’s saved address are valid, and you can enable Stripe Tax on Checkout sessions for that customer.
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.addressproperty. Otherwise, Checkout saves the billing address entered during the session to the customer’scustomer.addressproperty. 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.
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.
Check the responseOptional
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.