The Tax Calculation object

Tax

Tax Calculations

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_detailsobject
The customer’s details, such as address and tax IDs.
- customer_details.addressnullable object
  The customer’s postal address (for example, home or business location).
  customer_details.address.citynullable string
  City, district, suburb, town, or village.
  customer_details.address.countrystring
  Two-letter country code (ISO 3166-1 alpha-2).
  customer_details.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  customer_details.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  customer_details.address.postal_codenullable string
  ZIP or postal code.
  customer_details.address.statenullable string
  State/province as an ISO 3166-2 subdivision code, without country prefix. Example: “NY” or “TX”.
- customer_details.address_sourcenullable enum
  The type of customer address provided.
  Possible enum values
  billing
  Denotes the address as billing address.
  shipping
  Denotes the address as shipping address.
- customer_details.ip_addressnullable string
  The customer’s IP address (IPv4 or IPv6).
- customer_details.tax_idsarray of objects
  The customer’s tax IDs (for example, EU VAT numbers).
  customer_details.tax_ids.typeenum
  The type of the tax ID, one of ad_nrt, ar_cuit, eu_vat, bo_tin, br_cnpj, br_cpf, cn_tin, co_nit, cr_tin, do_rcn, ec_ruc, eu_oss_vat, hr_oib, pe_ruc, ro_tin, rs_pib, sv_nit, uy_ruc, ve_rif, vn_tin, gb_vat, nz_gst, au_abn, au_arn, in_gst, no_vat, no_voec, za_vat, ch_vat, mx_rfc, sg_uen, ru_inn, ru_kpp, ca_bn, hk_br, es_cif, tw_vat, th_vat, jp_cn, jp_rn, jp_trn, li_uid, my_itn, us_ein, kr_brn, ca_qst, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, my_sst, sg_gst, ae_trn, cl_tin, sa_vat, id_npwp, my_frp, il_vat, ge_vat, ua_vat, is_vat, bg_uic, hu_tin, si_tin, ke_pin, tr_tin, eg_tin, ph_tin, bh_vat, kz_bin, ng_tin, om_vat, de_stn, ch_uid, tz_vat, uz_vat, uz_tin, md_vat, ma_vat, by_tin, or unknown
  Possible enum values
  ad_nrt
  ae_trn
  ar_cuit
  au_abn
  au_arn
  bg_uic
  bh_vat
  bo_tin
  br_cnpj
  br_cpf
  Show 71 more
  customer_details.tax_ids.valuestring
  The value of the tax ID.
- customer_details.taxability_overrideenum
  The taxability override used for taxation.
  Possible enum values
  customer_exempt
  The customer is exempt of tax.
  none
  No taxability override (default).
  reverse_charge
  The customer is entitled to reverse charge tax treatment.

expires_atnullable timestamp
Timestamp of date at which the tax calculation will expire.

line_itemsnullable objectExpandable

The list of items the customer is purchasing.

line_items.objectstring
String representing the object’s type. Objects of the same type share the same value. Always has the value list.

line_items.dataarray of objects

Details about each object.

line_items.data.idstring
Unique identifier for the object.

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

line_items.data.amountinteger
The line item amount in the smallest currency unit. If tax_behavior=inclusive, then this amount includes taxes. Otherwise, taxes were calculated on top of this amount.

line_items.data.amount_taxinteger
The amount of tax calculated for this line item, in the smallest currency unit.

line_items.data.livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

line_items.data.productnullable string
The ID of an existing Product.

line_items.data.quantityinteger
The number of units of the item being purchased. For reversals, this is the quantity reversed.

line_items.data.referencenullable string
A custom identifier for this line item.

line_items.data.tax_behaviorenum
Specifies whether the amount includes taxes. If tax_behavior=inclusive, then the amount includes taxes.
Possible enum values
exclusive
Taxes are calculated on top of the line item amount (default).
inclusive
Taxes are included in the line item amount.

line_items.data.tax_breakdownnullable array of objectsExpandable

Detailed account of taxes relevant to this line item.

line_items.data.tax_breakdown.amountinteger
The amount of tax, in the smallest currency unit.

line_items.data.tax_breakdown.jurisdictionobject

The jurisdiction in which tax is imposed.

line_items.data.tax_breakdown.jurisdiction.countrystring
Two-letter country code (ISO 3166-1 alpha-2).

line_items.data.tax_breakdown.jurisdiction.display_namestring
A human-readable name for the jurisdiction imposing the tax.

line_items.data.tax_breakdown.jurisdiction.levelenum

Indicates the level of the jurisdiction imposing the tax.

Possible enum values

city

Level pertaining to city (e.g. Chicago)

country

Level pertaining to country (e.g. United States, Ireland, etc.)

county

Level pertaining to county (e.g. Cook)

district

Level pertaining to district (e.g. Roseland)

state

Level pertaining to state (e.g. Illinois)

line_items.data.tax_breakdown.jurisdiction.statenullable string
ISO 3166-2 subdivision code, without country prefix. For example, “NY” for New York, United States.

line_items.data.tax_breakdown.sourcingenum
Indicates whether the jurisdiction was determined by the origin (merchant’s address) or destination (customer’s address).
Possible enum values
destination
The tax is calculated at the customer’s address.
origin
The tax is calculated at one of your addresses, for example the main establishment.

line_items.data.tax_breakdown.tax_rate_detailsnullable object

Details regarding the rate for this tax. This field will be null when the tax is not imposed, for example if the product is exempt from tax.

line_items.data.tax_breakdown.tax_rate_details.display_namestring
A localized display name for tax type, intended to be human-readable. For example, “Local Sales and Use Tax”, “Value-added tax (VAT)”, or “Umsatzsteuer (USt.)”.

line_items.data.tax_breakdown.tax_rate_details.percentage_decimalstring
The tax rate percentage as a string. For example, 8.5% is represented as “8.5”.

line_items.data.tax_breakdown.tax_rate_details.tax_typeenum

The tax type, such as vat or sales_tax.

Possible enum values

amusement_tax

Amusement Tax

communications_tax

Communications Tax

gst

Goods and Services Tax

hst

Harmonized Sales Tax

igst

Integrated Goods and Services Tax

jct

Japanese Consumption Tax

lease_tax

Chicago Lease Tax

pst

Provincial Sales Tax

qst

Quebec Sales Tax

retail_delivery_fee

Retail Delivery Fee

Show 3 more

line_items.data.tax_breakdown.taxability_reasonenum

The reasoning behind this tax, for example, if the product is tax exempt. The possible values for this field may be extended as new tax rules are supported.

Possible enum values

customer_exempt

No tax is applied as the customer is exempt from tax.

not_collecting

No tax is collected either because you are not registered to collect tax in this jurisdiction, or because the non-taxable product tax code (txcd_00000000) was used.

not_subject_to_tax

No tax is imposed on this transaction.

not_supported

No tax applied. Stripe doesn’t support this jurisdiction, territory, or product.

portion_product_exempt

A portion of the price is exempt from tax.

portion_reduced_rated

A portion of the price is taxed at a reduced rate.

portion_standard_rated

A portion of the price is taxed at the standard rate.

product_exempt

The product or service is nontaxable or exempt from tax.

product_exempt_holiday

The product or service is not taxed due to a sales tax holiday.

proportionally_rated

The shipping cost tax rate is calculated as a weighted average of the other line items’ rates, weighted by their amounts.

Show 5 more

line_items.data.tax_breakdown.taxable_amountinteger
The amount on which tax is calculated, in the smallest currency unit.

line_items.data.tax_codestring
The tax code ID used for this resource.

line_items.has_moreboolean
True if this list has another page of items after this one that can be fetched.

line_items.urlstring
The URL where this list can be accessed.

shipping_costnullable object

The shipping cost details for the calculation.

shipping_cost.amountinteger
The shipping amount in the smallest currency unit. If tax_behavior=inclusive, then this amount includes taxes. Otherwise, taxes were calculated on top of this amount.

shipping_cost.amount_taxinteger
The amount of tax calculated for shipping, in the smallest currency unit.

shipping_cost.shipping_ratenullable string
The ID of an existing ShippingRate.

shipping_cost.tax_behaviorenum
Specifies whether the amount includes taxes. If tax_behavior=inclusive, then the amount includes taxes.
Possible enum values
exclusive
Taxes are calculated on top of the shipping cost amount (default).
inclusive
Taxes are included in the shipping cost amount.

shipping_cost.tax_breakdownnullable array of objectsExpandable

Detailed account of taxes relevant to shipping cost.

shipping_cost.tax_breakdown.amountinteger
The amount of tax, in the smallest currency unit.

shipping_cost.tax_breakdown.jurisdictionobject

The jurisdiction in which tax is imposed.

shipping_cost.tax_breakdown.jurisdiction.countrystring
Two-letter country code (ISO 3166-1 alpha-2).

shipping_cost.tax_breakdown.jurisdiction.display_namestring
A human-readable name for the jurisdiction imposing the tax.

shipping_cost.tax_breakdown.jurisdiction.levelenum

Indicates the level of the jurisdiction imposing the tax.

Possible enum values

city

Level pertaining to city (e.g. Chicago)

country

Level pertaining to country (e.g. United States, Ireland, etc.)

county

Level pertaining to county (e.g. Cook)

district

Level pertaining to district (e.g. Roseland)

state

Level pertaining to state (e.g. Illinois)

shipping_cost.tax_breakdown.jurisdiction.statenullable string
ISO 3166-2 subdivision code, without country prefix. For example, “NY” for New York, United States.

shipping_cost.tax_breakdown.sourcingenum
Indicates whether the jurisdiction was determined by the origin (merchant’s address) or destination (customer’s address).
Possible enum values
destination
The tax is calculated at the customer’s address.
origin
The tax is calculated at one of your addresses, for example the main establishment.

shipping_cost.tax_breakdown.tax_rate_detailsnullable object

Details regarding the rate for this tax. This field will be null when the tax is not imposed, for example if the product is exempt from tax.

shipping_cost.tax_breakdown.tax_rate_details.display_namestring
A localized display name for tax type, intended to be human-readable. For example, “Local Sales and Use Tax”, “Value-added tax (VAT)”, or “Umsatzsteuer (USt.)”.

shipping_cost.tax_breakdown.tax_rate_details.percentage_decimalstring
The tax rate percentage as a string. For example, 8.5% is represented as “8.5”.

shipping_cost.tax_breakdown.tax_rate_details.tax_typeenum

The tax type, such as vat or sales_tax.

Possible enum values

amusement_tax

Amusement Tax

communications_tax

Communications Tax

gst

Goods and Services Tax

hst

Harmonized Sales Tax

igst

Integrated Goods and Services Tax

jct

Japanese Consumption Tax

lease_tax

Chicago Lease Tax

pst

Provincial Sales Tax

qst

Quebec Sales Tax

retail_delivery_fee

Retail Delivery Fee

Show 3 more

shipping_cost.tax_breakdown.taxability_reasonenum

The reasoning behind this tax, for example, if the product is tax exempt. The possible values for this field may be extended as new tax rules are supported.

Possible enum values

customer_exempt

No tax is applied as the customer is exempt from tax.

not_collecting

No tax is collected either because you are not registered to collect tax in this jurisdiction, or because the non-taxable product tax code (txcd_00000000) was used.

not_subject_to_tax

No tax is imposed on this transaction.

not_supported

No tax applied. Stripe doesn’t support this jurisdiction, territory, or product.

portion_product_exempt

A portion of the price is exempt from tax.

portion_reduced_rated

A portion of the price is taxed at a reduced rate.

portion_standard_rated

A portion of the price is taxed at the standard rate.

product_exempt

The product or service is nontaxable or exempt from tax.

product_exempt_holiday

The product or service is not taxed due to a sales tax holiday.

proportionally_rated

The shipping cost tax rate is calculated as a weighted average of the other line items’ rates, weighted by their amounts.

Show 5 more

shipping_cost.tax_breakdown.taxable_amountinteger
The amount on which tax is calculated, in the smallest currency unit.

shipping_cost.tax_codestring
The tax code ID used for shipping.

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 objects

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

tax_breakdown.amountinteger
The amount of tax, in the smallest currency unit.

tax_breakdown.inclusiveboolean
Specifies whether the tax amount is included in the line item amount.

tax_breakdown.tax_rate_detailsobject

Details of the applied tax rate, such as type, percentage, state and country.

tax_breakdown.tax_rate_details.countrynullable string
Two-letter country code (ISO 3166-1 alpha-2).

tax_breakdown.tax_rate_details.flat_amountnullable object
The amount of the tax rate when the rate_type is flat_amount. Tax rates with rate_type percentage can vary based on the transaction, resulting in this field being null. This field exposes the amount and currency of the flat tax rate.
- tax_breakdown.tax_rate_details.flat_amount.amountinteger
  Amount of the tax when the rate_type is flat_amount. This positive integer represents how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
- tax_breakdown.tax_rate_details.flat_amount.currencystring
  Three-letter ISO currency code, in lowercase.

tax_breakdown.tax_rate_details.percentage_decimalstring
The tax rate percentage as a string. For example, 8.5% is represented as "8.5".

tax_breakdown.tax_rate_details.rate_typenullable enum

Indicates the type of tax rate applied to the taxable amount. This value can be null when no tax applies to the location.

Possible enum values

flat_amount

A fixed amount applied as tax, regardless of the taxable amount, such as a retail delivery fee.

percentage

A tax rate expressed as a percentage of the taxable amount, such as the sales tax rate in California.

tax_breakdown.tax_rate_details.statenullable string
State, county, province, or region.

tax_breakdown.tax_rate_details.tax_typenullable enum

The tax type, such as vat or sales_tax.

Possible enum values

amusement_tax

Amusement Tax

communications_tax

Communications Tax

gst

Goods and Services Tax

hst

Harmonized Sales Tax

igst

Integrated Goods and Services Tax

jct

Japanese Consumption Tax

lease_tax

Chicago Lease Tax

pst

Provincial Sales Tax

qst

Quebec Sales Tax

retail_delivery_fee

Retail Delivery Fee

Show 3 more

tax_breakdown.taxability_reasonenum

The reasoning behind this tax, for example, if the product is tax exempt. We might extend the possible values for this field to support new tax rules.

Possible enum values

customer_exempt

No tax is applied as the customer is exempt from tax.

not_collecting

No tax is collected either because you are not registered to collect tax in this jurisdiction, or because the non-taxable product tax code (txcd_00000000) was used.

not_subject_to_tax

No tax is imposed on this transaction.

not_supported

No tax applied. Stripe doesn’t support this jurisdiction, territory, or product.

portion_product_exempt

A portion of the price is exempt from tax.

portion_reduced_rated

A portion of the price is taxed at a reduced rate.

portion_standard_rated

A portion of the price is taxed at the standard rate.

product_exempt

The product or service is nontaxable or exempt from tax.

product_exempt_holiday

The product or service is not taxed due to a sales tax holiday.

proportionally_rated

The shipping cost tax rate is calculated as a weighted average of the other line items’ rates, weighted by their amounts.

Show 5 more

tax_breakdown.taxable_amountinteger
The amount on which tax is calculated, in the smallest currency unit.

More attributes

customernullable string
The ID of an existing Customer used for the resource.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

ship_from_detailsnullable object
The details of the ship from location, such as the address.
- ship_from_details.addressobject
  The address from which the goods in the transaction are shipped from.
  ship_from_details.address.citynullable string
  City, district, suburb, town, or village.
  ship_from_details.address.countrystring
  Two-letter country code (ISO 3166-1 alpha-2).
  ship_from_details.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  ship_from_details.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  ship_from_details.address.postal_codenullable string
  ZIP or postal code.
  ship_from_details.address.statenullable string
  State/province as an ISO 3166-2 subdivision code, without country prefix. Example: “NY” or “TX”.

tax_datetimestamp
Timestamp of date at which the tax rules and rates in effect applies for the calculation.

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
}

The Tax Calculation object

Attributes

idnullable string

objectstring

amount_totalinteger

currencystring

customer_detailsobject

customer_details.addressnullable object

customer_details.address.citynullable string

customer_details.address.countrystring

customer_details.address.line1nullable string

customer_details.address.line2nullable string

customer_details.address.postal_codenullable string

customer_details.address.statenullable string

customer_details.address_sourcenullable enum

customer_details.ip_addressnullable string

customer_details.tax_idsarray of objects

customer_details.tax_ids.typeenum

customer_details.tax_ids.valuestring

customer_details.taxability_overrideenum

expires_atnullable timestamp

line_itemsnullable objectExpandable

line_items.objectstring

line_items.dataarray of objects

line_items.data.idstring

line_items.data.objectstring

line_items.data.amountinteger

line_items.data.amount_taxinteger

line_items.data.livemodeboolean

line_items.data.productnullable string

line_items.data.quantityinteger

line_items.data.referencenullable string

line_items.data.tax_behaviorenum

line_items.data.tax_breakdownnullable array of objectsExpandable

line_items.data.tax_breakdown.amountinteger

line_items.data.tax_breakdown.jurisdictionobject

line_items.data.tax_breakdown.jurisdiction.countrystring

line_items.data.tax_breakdown.jurisdiction.display_namestring

line_items.data.tax_breakdown.jurisdiction.levelenum

line_items.data.tax_breakdown.jurisdiction.statenullable string

line_items.data.tax_breakdown.sourcingenum

line_items.data.tax_breakdown.tax_rate_detailsnullable object

line_items.data.tax_breakdown.tax_rate_details.display_namestring

line_items.data.tax_breakdown.tax_rate_details.percentage_decimalstring

line_items.data.tax_breakdown.tax_rate_details.tax_typeenum

line_items.data.tax_breakdown.taxability_reasonenum

line_items.data.tax_breakdown.taxable_amountinteger

line_items.data.tax_codestring

line_items.has_moreboolean

line_items.urlstring

shipping_costnullable object

shipping_cost.amountinteger

shipping_cost.amount_taxinteger

shipping_cost.shipping_ratenullable string

shipping_cost.tax_behaviorenum

shipping_cost.tax_breakdownnullable array of objectsExpandable

shipping_cost.tax_breakdown.amountinteger

shipping_cost.tax_breakdown.jurisdictionobject

shipping_cost.tax_breakdown.jurisdiction.countrystring

shipping_cost.tax_breakdown.jurisdiction.display_namestring

shipping_cost.tax_breakdown.jurisdiction.levelenum

shipping_cost.tax_breakdown.jurisdiction.statenullable string

shipping_cost.tax_breakdown.sourcingenum

shipping_cost.tax_breakdown.tax_rate_detailsnullable object

shipping_cost.tax_breakdown.tax_rate_details.display_namestring

shipping_cost.tax_breakdown.tax_rate_details.percentage_decimalstring

shipping_cost.tax_breakdown.tax_rate_details.tax_typeenum

shipping_cost.tax_breakdown.taxability_reasonenum

shipping_cost.tax_breakdown.taxable_amountinteger

shipping_cost.tax_codestring

tax_amount_exclusiveinteger

tax_amount_inclusiveinteger

tax_breakdownarray of objects

tax_breakdown.amountinteger

tax_breakdown.inclusiveboolean

tax_breakdown.tax_rate_detailsobject

tax_breakdown.tax_rate_details.countrynullable string

tax_breakdown.tax_rate_details.flat_amountnullable object

tax_breakdown.tax_rate_details.flat_amount.amountinteger

tax_breakdown.tax_rate_details.flat_amount.currencystring

More attributes