Automatically collect tax on Checkout sessions

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:

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.

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"

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 either base tax calculations on the customer’s existing addresses or new addresses collected during the session:

Use the existing addresses on the customer for taxes

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

• The customer address that Checkout uses 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.

• Customer address 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 addresses are valid, and you can enable Stripe Tax on Checkout sessions for that customer.

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 the 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.

• The address that Checkout uses for taxes: If you collect 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 Checkout saves the addresses collected during checkout: If you collect 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 collect shipping addresses with Checkout, set the customer_update[shipping] property to auto so that you copy the shipping information from Checkout to the customer.

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 don’t collect 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.

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[address]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

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.