Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer tools
Overview
Billing
Tax
    Overview
    Get started
    How Tax works
    Set up
    Using the Settings API
    Testing
    Integrate by payment flow
    Payment Links
    Checkout
    Invoicing
    Subscriptions
    Rate card subscriptions
    Custom payment integration
    Payment Intents APIs
    Integrate with Stripe Connect
    Overview
    Tax for software platforms
    Tax for marketplaces
    Manage your compliance
    Monitor your obligations
    Register
    Calculate tax
    Report
    Third-Party Tax Apps
    File and Remit
    Tax Reference
    Product tax codes
    Supported countries
    FAQ
Reporting
Data
Startup incorporation
HomeRevenueTax

Calculate tax in your custom payment flowsPublic 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.

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

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
curl https://api.stripe.com/v1/payment_intents \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Version: 2025-05-28.preview" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=true \ -d "hooks[inputs][tax][calculation]"=
{{CALCULATION_ID}}

Supported endpoints

The following endpoints support setting a calculation on a PaymentIntent.

  • Create: /v1/payment_intents
  • Update: /v1/payment_intents/:id
  • Confirm: /v1/payment_intents/:id/confirm
  • Capture: /v1/payment_intents/:id/capture

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.

OptionalRetrieve automatically committed tax transactions

See also

  • Tax API for Sales Tax, GST, and VAT
  • Custom payment flow guide
  • Reporting and filing
  • Use Stripe Tax with Connect
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
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