Sample - Stripe API
POST/v1/tax/calculations

Create a Calculation

Calculates tax based on the input and returns a Tax Calculation object.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
customerstringoptional
The ID of an existing customer to use for this calculation. If provided, the customer's address and tax IDs are copied to `customer_details`.
customer_detailsobjectoptional
Details about the customer, including address and tax IDs.
expandarray<string>optional
Specifies which fields in the response should be expanded.
line_itemsarray<CalculationLineItem>required
A list of items the customer is purchasing. You can pass up to 100 line items, or 1,000 if your account has an increased limit.
ship_from_detailsobjectoptional
Details about the address from which the goods are being shipped.
shipping_costobjectoptional
Shipping cost details to be used for the calculation.
tax_dateintegeroptional
The calculation uses the tax rules and rates that are in effect at this timestamp. You can use a date up to 31 days in the past or up to 31 days in the future. If you use a future date, Stripe doesn't guarantee that the expected tax rules and rate being used match the actual rules and rate that will be in effect on that date. We deploy tax changes before their effective date, but not within a fixed window.

2 status codes
200Successful response.
amount_totalintegerrequired
Total amount after taxes in the [smallest currency unit](https://docs.stripe.com/currencies#minor-units).
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
customerstringoptional
The ID of an existing [Customer](https://docs.stripe.com/api/customers/object) used for the resource.
customer_detailsobjectrequired
expires_atintegeroptional
Timestamp of date at which the tax calculation will expire.
idstringoptional
Unique identifier for the calculation.
line_itemsobjectoptional
The list of items the customer is purchasing.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:tax.calculation
ship_from_detailsobjectoptional
The details of the ship from location, such as the address.
shipping_costobjectoptional
The shipping cost details for the calculation.
tax_amount_exclusiveintegerrequired
The amount of tax to be collected on top of the line item prices.
tax_amount_inclusiveintegerrequired
The amount of tax already included in the line item prices.
tax_breakdownarray<TaxProductResourceTaxBreakdown>required
Breakdown of individual tax amounts that add up to the total.
tax_dateintegerrequired
The calculation uses the tax rules and rates that are in effect at this timestamp. You can use a date up to 31 days in the past or up to 31 days in the future. If you use a future date, Stripe doesn't guarantee that the expected tax rules and rate being used match the actual rules and rate that will be in effect on that date. We deploy tax changes before their effective date, but not within a fixed window.
defaultError response.
errorobjectrequired

Error handling

Any other status is an error: Error response.