Tax Calculations 

A Tax Calculation allows you to calculate the tax to collect from your customer.

Related guide: Calculate tax in your custom payment flow

The Tax Calculation object 

Attributes

  • idnullable string

    Unique identifier for the calculation.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • amount_totalinteger

    Total amount after taxes in the smallest currency unit.

  • currencystring

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • customer_detailsDictionary

    The customer’s details, such as address and tax IDs.

  • expires_atnullable timestamp

    Timestamp of date at which the tax calculation will expire.

  • line_itemsnullable DictionaryExpandable

    The list of items the customer is purchasing.

  • shipping_costnullable Dictionary

    The shipping cost details for the calculation.

  • tax_amount_exclusiveinteger

    The amount of tax to be collected on top of the line item prices.

  • tax_amount_inclusiveinteger

    The amount of tax already included in the line item prices.

  • tax_breakdownarray of Dictionaries

    Breakdown of individual tax amounts that add up to the total.

More attributes

  • customernullable string

  • livemodeboolean

  • ship_from_detailsnullable Dictionary

  • tax_datetimestamp

The Tax Calculation object
{
"id": "taxcalc_1OduxkBUZ691iUZ4iWvpMApI",
"object": "tax.calculation",
"amount_total": 1953,
"currency": "usd",
"customer": null,
"customer_details": {
"address": {
"city": "Seattle",
"country": "US",
"line1": "920 5th Ave",
"line2": null,
"postal_code": "98104",
"state": "WA"
},
"address_source": "shipping",
"ip_address": null,
"tax_ids": [],
"taxability_override": "none"
},
"expires_at": 1706708005,
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_PSqf3RMNZa23H4",
"object": "tax.calculation_line_item",
"amount": 1499,
"amount_tax": 154,
"livemode": false,
"product": null,
"quantity": 1,
"reference": "Music Streaming Coupon",
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/calculations/taxcalc_1OduxkBUZ691iUZ4iWvpMApI/line_items"
},
"livemode": false,
"ship_from_details": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"tax_amount_exclusive": 154,
"tax_amount_inclusive": 0,
"tax_breakdown": [
{
"amount": 154,
"inclusive": false,
"tax_rate_details": {
"country": "US",
"percentage_decimal": "10.25",
"state": "WA",
"tax_type": "sales_tax"
},
"taxability_reason": "standard_rated",
"taxable_amount": 1499
},
{
"amount": 0,
"inclusive": false,
"tax_rate_details": {
"country": "DE",
"percentage_decimal": "0.0",
"state": null,
"tax_type": "vat"
},
"taxability_reason": "zero_rated",
"taxable_amount": 300
}
],
"tax_date": 1706535204
}

Create a Tax Calculation 

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

Parameters

  • currencyenumRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • line_itemsarray of DictionariesRequired

    A list of items the customer is purchasing.

  • customer_detailsDictionaryRequired unless customer provided

    Details about the customer, including address and tax IDs.

  • shipping_costDictionary

    Shipping cost details to be used for the calculation.

More parameters

  • customerstringRequired unless customer_details provided

  • ship_from_detailsDictionary

  • tax_dateinteger

Returns

A Tax Calculation object containing the first 100 input line_items if the calculation succeeds. Otherwise, an error (for example, indicating that the customer address was invalid).

POST /v1/tax/calculations
StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var options = new Stripe.Tax.CalculationCreateOptions
{
Currency = "usd",
CustomerDetails = new Stripe.Tax.CalculationCustomerDetailsOptions
{
Address = new AddressOptions
{
Line1 = "920 5th Ave",
City = "Seattle",
State = "WA",
PostalCode = "98104",
Country = "US",
},
AddressSource = "shipping",
},
LineItems = new List<Stripe.Tax.CalculationLineItemOptions>
{
new Stripe.Tax.CalculationLineItemOptions
{
Amount = 1499,
TaxCode = "txcd_10000000",
Reference = "Music Streaming Coupon",
},
},
ShippingCost = new Stripe.Tax.CalculationShippingCostOptions { Amount = 300 },
Expand = new List<string> { "line_items" },
};
var service = new Stripe.Tax.CalculationService();
Stripe.Tax.Calculation calculation = service.Create(options);
Response
{
"id": "taxcalc_1OduxkBUZ691iUZ4iWvpMApI",
"object": "tax.calculation",
"amount_total": 1953,
"currency": "usd",
"customer": null,
"customer_details": {
"address": {
"city": "Seattle",
"country": "US",
"line1": "920 5th Ave",
"line2": null,
"postal_code": "98104",
"state": "WA"
},
"address_source": "shipping",
"ip_address": null,
"tax_ids": [],
"taxability_override": "none"
},
"expires_at": 1706708005,
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_PSqf3RMNZa23H4",
"object": "tax.calculation_line_item",
"amount": 1499,
"amount_tax": 154,
"livemode": false,
"product": null,
"quantity": 1,
"reference": "Music Streaming Coupon",
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/calculations/taxcalc_1OduxkBUZ691iUZ4iWvpMApI/line_items"
},
"livemode": false,
"ship_from_details": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"tax_amount_exclusive": 154,
"tax_amount_inclusive": 0,
"tax_breakdown": [
{
"amount": 154,
"inclusive": false,
"tax_rate_details": {
"country": "US",
"percentage_decimal": "10.25",
"state": "WA",
"tax_type": "sales_tax"
},
"taxability_reason": "standard_rated",
"taxable_amount": 1499
},
{
"amount": 0,
"inclusive": false,
"tax_rate_details": {
"country": "DE",
"percentage_decimal": "0.0",
"state": null,
"tax_type": "vat"
},
"taxability_reason": "zero_rated",
"taxable_amount": 300
}
],
"tax_date": 1706535204
}

Retrieve a calculation's line items 

Retrieves the line items of a tax calculation as a collection, if the calculation hasn’t expired.

Parameters

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of Line Item objects if the Tax calculation is found. Otherwise returns a ‘not found’ error.

GET /v1/tax/calculations/:id/line_items
StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var options = new Stripe.Tax.CalculationLineItemListOptions { Limit = 3 };
var service = new Stripe.Tax.CalculationLineItemService();
StripeList<Stripe.Tax.CalculationLineItem> calculationLineItems = service.List(
"taxcalc_1NpJD42eZvKYlo2CUti522cz",
options);
Response
{
"object": "list",
"url": "/v1/tax/calculations/taxcalc_1NpJD42eZvKYlo2CUti522cz/line_items",
"has_more": false,
"data": [
{
"id": "tax_li_OcYJb5mQOSSSWD",
"object": "tax.calculation_line_item",
"amount": 1499,
"amount_tax": 148,
"livemode": false,
"product": null,
"quantity": 1,
"reference": "Pepperoni Pizza",
"tax_behavior": "exclusive",
"tax_code": "txcd_40060003"
}
]
}

Retrieve a Tax Calculation 

Retrieves a Tax Calculation object, if the calculation hasn’t expired.

Parameters

No parameters.

Returns

A Tax Calculation object if the Tax calculation is found. Otherwise returns a ‘not found’ error.

GET /v1/tax/calculations/:id
StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var service = new Stripe.Tax.CalculationService();
Stripe.Tax.Calculation calculation = service.Get("taxcalc_1OduxkBUZ691iUZ4iWvpMApI");
Response
{
"id": "taxcalc_1OduxkBUZ691iUZ4iWvpMApI",
"object": "tax.calculation",
"amount_total": 1953,
"currency": "usd",
"customer": null,
"customer_details": {
"address": {
"city": "Seattle",
"country": "US",
"line1": "920 5th Ave",
"line2": null,
"postal_code": "98104",
"state": "WA"
},
"address_source": "shipping",
"ip_address": null,
"tax_ids": [],
"taxability_override": "none"
},
"expires_at": 1706708005,
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_PSqf3RMNZa23H4",
"object": "tax.calculation_line_item",
"amount": 1499,
"amount_tax": 154,
"livemode": false,
"product": null,
"quantity": 1,
"reference": "Music Streaming Coupon",
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/calculations/taxcalc_1OduxkBUZ691iUZ4iWvpMApI/line_items"
},
"livemode": false,
"ship_from_details": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"tax_amount_exclusive": 154,
"tax_amount_inclusive": 0,
"tax_breakdown": [
{
"amount": 154,
"inclusive": false,
"tax_rate_details": {
"country": "US",
"percentage_decimal": "10.25",
"state": "WA",
"tax_type": "sales_tax"
},
"taxability_reason": "standard_rated",
"taxable_amount": 1499
},
{
"amount": 0,
"inclusive": false,
"tax_rate_details": {
"country": "DE",
"percentage_decimal": "0.0",
"state": null,
"tax_type": "vat"
},
"taxability_reason": "zero_rated",
"taxable_amount": 300
}
],
"tax_date": 1706535204
}