Tax Calculations

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

Endpoints

POST/v1/tax/calculations

GET/v1/tax/calculations/:id/line_items

GET/v1/tax/calculations/:id

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_detailsobject
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 objectExpandable
The list of items the customer is purchasing.

shipping_costnullable object
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 objects
Breakdown of individual tax amounts that add up to the total.

More attributes

customernullable string

livemodeboolean

ship_from_detailsnullable object

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 objectsRequired
A list of items the customer is purchasing.

customer_detailsobjectRequired unless customer provided
Details about the customer, including address and tax IDs.

shipping_costobject
Shipping cost details to be used for the calculation.

More parameters

customerstringRequired unless customer_details provided

ship_from_detailsobject

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

Server-side language

curl https://api.stripe.com/v1/tax/calculations \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d currency=usd \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping \
  -d "line_items[0][amount]"=1499 \
  -d "line_items[0][tax_code]"=txcd_10000000 \
  -d "line_items[0][reference]"="Music Streaming Coupon" \
  -d "shipping_cost[amount]"=300 \
  -d "expand[0]"=line_items

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

Server-side language

curl -G https://api.stripe.com/v1/tax/calculations/taxcalc_1NpJD42eZvKYlo2CUti522cz/line_items \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3

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

Server-side language

curl https://api.stripe.com/v1/tax/calculations/taxcalc_1OduxkBUZ691iUZ4iWvpMApI \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

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
}

Tax Calculations

The Tax Calculation object

Attributes

idnullable string

objectstring

amount_totalinteger

currencystring

customer_detailsobject

expires_atnullable timestamp

line_itemsnullable objectExpandable

shipping_costnullable object

tax_amount_exclusiveinteger

tax_amount_inclusiveinteger

tax_breakdownarray of objects

More attributesExpand all

customernullable string

livemodeboolean

ship_from_detailsnullable object

tax_datetimestamp

Create a Tax Calculation

Parameters

currencyenumRequired

line_itemsarray of objectsRequired

customer_detailsobjectRequired unless customer provided

shipping_costobject

More parametersExpand all

customerstringRequired unless customer_details provided

ship_from_detailsobject

tax_dateinteger

Returns

Retrieve a calculation's line items

Parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

Retrieve a Tax Calculation

Parameters

Returns

More attributes

More parameters