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.
Optional Collect 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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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.