Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

Calculate tax in your custom payment flowsPrivate preview

Learn how to integrate taxes with the Stripe Tax and Payment Intents APIs.

Copy page

The Stripe Tax API enables you to calculate tax in your custom payment flows. If you use the Payment Intents API, Stripe can submit tax transactions in the payment lifecycle.

Private preview

This feature is currently in Private preview. Users without preview access can use the Tax API to integrate Stripe Tax with payment intents.

Calculate tax

You can integrate the Tax API with a PaymentIntent by associating it with a Tax Calculation object. Use calculate tax to get a new Tax Calculation object with information about how much tax to collect.

Command Line
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][tax_code]"=txcd_99999999 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping

Link tax calculation to the PaymentIntent

Private preview

This feature is currently in Private preview. Users without preview access can use the Tax API to integrate Stripe Tax with payment intents.

When creating or modifying a PaymentIntent, include the Tax Calculation ID and set the amount to the amount_total of the Tax Calculation object.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.basil; payment_intent_with_tax_api_beta=v1;" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d "async_workflows[inputs][tax][calculation]"=
{{CALCULATION_ID}}

Supported endpoints

The following endpoints support setting a calculation on a PaymentIntent.

Limitations

  • You can only link new calculations to a PaymentIntent until it transitions to a succeeded state.
  • A tax calculation can transition to only one tax Transaction. If multiple PaymentIntents transition to a succeeded state with the same linked calculation, accounting reflects only the first one.

Resulting Stripe actions

If the PaymentIntent is correctly linked to the Tax Calculation object, Stripe automatically:

  • Creates a tax transaction from the calculation after the PaymentIntent transitions to a succeeded state
  • Performs a tax reversal of a tax transaction for any refunds (created with API or Dashboard) for the PaymentIntent
  • Creates a tax reversal for a reversal, if a refund has failed
  • Includes the total tax information in PaymentIntent receipts

Stripe won’t:

  • Change the PaymentIntent amount based on the linked tax calculation
  • Alter the tax transaction amount based on the PaymentIntent captured amount
  • Automatically create a tax reversal for disputes

Integrate taxes for your Connect platform with the Stripe Tax and Payment Intents APIs

The Payment Intents API works with connected accounts on your Connect platform. This means that if you calculate tax using a connected account, you can link the tax calculation to a Payment Intent created using that connected account.

See also

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc
Related Guides
Stripe Tax with Payment Links
Stripe Tax with Checkout
Stripe Tax with Invoicing
Stripe Tax with custom payment flows
Products Used
Tax
Payments