Tax calculations

This endpoint calculates tax for an invoice based on the provided request data. To learn more about how tax is calculated, see the tax calculation guide.

It processes the invoice details and returns calculated tax information, including individual tax items and total tax due.

• Input: Details about the invoice.
• Output: Response with total tax due and calculated tax details broken up by line item and jurisdiction.

Raises an HTTPException if there’s an error processing while the request, translating to a non 200 status code response.

POST /calculations

Calculate Tax for Invoice

cURL

curl --request POST \
  --url https://api.taxwire.com/calculations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "currency": "USD",
  "discount_amount": "100",
  "vendor_discount_amount": "100",
  "transaction_date": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "customer": {
        "address": {
          "city": "Anytown",
          "line1": "123 Main St",
          "postal_code": "12345",
          "state": "CA"
        },
        "tax_ids": [
          {
            "country": "DE",
            "type": "eu_vat",
            "value": "DE123456789"
          }
        ]
      },
      "id": "item_123",
      "product": {
        "tax_attributes": [
          "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
        ]
      },
      "quantity": "1",
      "unit_price": "100"
    }
  ]
}
'

200

{
  "currency": "USD",
  "tax_amount": "6.00",
  "line_items": [
    {
      "id": "item_30a5c567-1f74-4ae7-a3f9-c2740dc7497c",
      "tax_amount": "6.00",
      "taxes": [
        {
          "jurisdiction_name": "MICHIGAN",
          "jurisdiction_type": "state",
          "tax_amount": "6.00",
          "tax_type": "MICHIGAN RETAILER USE TAX"
        }
      ]
    }
  ]
}

Note on registrations

By default, tax will be calculated as zero if you attempt to perform a calculation in a customer location where your company is not yet registered. If you provide an X-Include-Unregistered: true header, this requirement is overridden, and tax will be nonzero in some cases even when unregistered in that jurisdiction.

Authorizations

X-API-Key · string · header · required

Body

application/json

Create calculation request model.

currency · string · default: USD

The currency of the transaction. Defaults to USD. The currency must be a valid ISO 4217 currency code.

Required string length: 3

Example:

"USD"

discount_amount · string | null

Amount of discount applied to the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

vendor_discount_amount · string | null

Amount of discount applied to the vendor in the transaction. Most of the time, you should use the discount_amount field instead. Unlike discount_amount, this discount is funded by the vendor and typically does not reduce the taxable base of the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

transaction_date · string<date-time>

Date and time for the tax calculation. Timezone is required for better accuracy. Use the ISO 8601 format. e.g: 2024-03-15T12:00:00Z. If not provided, the current UTC date and time will be used.

Example:

"2024-03-15T12:00:00Z"

line_items · LineItem · object[] | null

List of line items for an invoice or transaction. Required for sale transactions, optional for credits. A credit transaction without line_items will be assumed to be a full refund of the invoice.

Show child attributes

Example:

[
  {
    "customer": {
      "address": {
        "city": "Anytown",
        "line1": "123 Main St",
        "postal_code": "12345",
        "state": "CA"
      },
      "tax_ids": [
        {
          "country": "DE",
          "type": "eu_vat",
          "value": "DE123456789"
        }
      ]
    },
    "id": "item_123",
    "product": {
      "tax_attributes": [
        "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
      ]
    },
    "quantity": "1",
    "unit_price": "100"
  }
]

Response

200

application/json

Successfully calculated tax for the invoice

Response model containing the calculated tax details for an invoice.

tax_amount · string · required

line_items · object[] · required

Show child attributes

currency · string