Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

Collect taxes

Learn how to collect taxes with Stripe Tax.

Stripe Tax allows you to calculate the tax on your one-time and recurring payments when you use Checkout. You can enable Stripe Tax to automatically compute taxes on all of your Checkout purchases and subscriptions.

Create a Checkout Session

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

To calculate tax for new customers, Checkout validates and uses the provided shipping or billing address. For existing customers, Checkout calculates tax by validating and using the attached customer shipping or billing address. If you capture a new billing or shipping address for an existing customer, Checkout won’t automatically override the previous billing or shipping information. You must explicitly request customer address changes.

Apple Pay and Google Pay

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

If you don’t pass in an existing customer when creating a Checkout session, Checkout creates a new customer and automatically saves the billing address and shipping information. 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
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 mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

OptionalUpdate your products and prices

Stripe Tax uses information stored on products and prices to calculate tax, such as tax code and tax behavior. 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 behavior.

OptionalCalculate tax for existing customers

To calculate tax on an existing customer’s Checkout session, set the automatic_tax[enabled] parameter to true when you create the session. You can base the tax calculations on the customer’s existing addresses or the new addresses that you collected during checkout:

Use existing addresses on the customer for taxes

If you’ve already collected your existing customers’ addresses, you can base the 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 their customer.tax.automatic_tax property. If customer.tax.automatic_tax value is supported or not_collecting, the customer’s saved addresses are valid, and you can enable Stripe Tax on Checkout sessions for that customer.

Command Line
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 mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Use addresses collected during Checkout for taxes

You can configure Checkout to save a customer’s new billing or shipping addresses. In this case, Checkout calculates the tax by 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 will override any existing addresses.

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

Command Line
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[shipping]"=auto \
  -d "shipping_address_collection[allowed_countries][0]"=US \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode 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
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[shipping]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

OptionalCheck the response

To see the results of the latest tax calculation, the total_details.amount_tax property in the Checkout Session resource shows the calculated tax amount. Additionally, you can use the Dashboard to view the tax outcome for each payment.

Was this page helpful?
YesNo