Stripe Tax with PaymentIntents

Calculate and collect tax in custom payment flows using the Stripe Tax API.

Use the Stripe Tax API to calculate and collect tax in your PaymentIntents integration. After calculating tax, attach the calculation to a PaymentIntent and Stripe records the transaction for reporting.

Choose your integration

Stripe offers two ways to handle tax with PaymentIntents:

Simplified: Stripe automatically manages tax transactions and reversals. Refund reversals use flat-amount distribution. Best for most use cases.
Custom: You manually record tax transactions and control reversals at the line-item level. Use this if you need fine-grained control.

For Checkout, Invoicing, or Subscriptions, use their built-in Stripe Tax integrations instead.

Add registrations

Stripe Tax only calculates tax in jurisdictions where you’re registered to collect tax. You must add your registrations in the Dashboard.

OptionalCollect customer address
Client-side

Calculate tax
Server-side

You choose when and how often to calculate tax. For example, you can:

Show a tax estimate based on the customer’s IP address when they enter your checkout flow
Recalculate tax as your customer types their billing or shipping address
Calculate the final tax amount to collect when your customer finishes typing their address

Stripe charges a fee per tax calculation API call. You can throttle tax calculation API calls to manage your costs.

The examples below show how to calculate tax in a variety of scenarios. Stripe Tax only calculates tax in jurisdictions where you’re registered to collect tax. You must add your registrations in the Dashboard.

Example:

This example calculates tax for a US shipping address. The line item has a price of 10 USD and uses your account’s preset tax code.

The calculation response contains amounts you can display to your customer, and use to take payment:

Attribute	Description
amount_total	The grand total after calculating tax. Use this to set the PaymentIntent amount to charge your customer.
tax_amount_exclusive	The amount of tax added on top of your line item amounts and shipping cost. This tax amount increases the `amount_total`. Use this to show your customer the amount of tax added to the transaction subtotal.
tax_amount_inclusive	The amount of tax that’s included in your line item amounts and shipping cost (if using tax-inclusive pricing). This tax amount doesn’t increase the `amount_total`. Use this to show your customer the tax included in the total they’re paying.
tax_breakdown	A list of tax amounts broken out by country or state tax rate. Use this to show your customer the specific taxes you’re collecting.

Handle customer location errors

If your customer’s address is invalid or isn’t precise enough to calculate tax, the calculation returns the customer_tax_location_invalid error code:

{
  "error": {
    "doc_url": "https://docs.stripe.com/error-codes#customer-tax-location-invalid",
    "code": "customer_tax_location_invalid",
    "message": "We could not determine the customer's tax location based on the provided customer address.",
    "param": "customer_details[address]",
    "type": "invalid_request_error"
  }
}

If you receive this error, prompt your customer to check the address they entered and fix any typos.

Next steps

Choose how to handle tax transactions and reversals:

Simplified integration: Attach the calculation to a PaymentIntent and Stripe automatically creates tax transactions on payment success, and records reversals on refunds.
Custom integration: Manually create tax transactions from calculations, with line-item level control over reversals.

Testing

Use sandboxes to confirm your integration works correctly before going live. Sandbox responses are identical in structure to responses in live mode.

Warning

In testing environments, calculations aren’t guaranteed to return up-to-date taxation results. You’re limited to 1,000 tax calculations per day. If you need a higher limit, contact Stripe support. For guidance on automated testing and strategies to avoid rate limits in testing environments, see Automated testing.

View tax transactions

You can view all tax transactions for your account on the Tax Transactions page in the Dashboard. Click an individual transaction to see a detailed breakdown of calculated tax by jurisdiction, and by the individual products included in the transaction.

Note

The Tax Transactions page only includes transactions and not calculations. If you expect to see a calculation and can’t find it on this page, verify that you successfully created a tax transaction from the calculation.