> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.taxwire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/guides/calculate_taxes).

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.


### 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.


## OpenAPI

````yaml POST /calculations
openapi: 3.1.0
info:
  title: Taxwire Public API
  version: 0.1.0
servers: []
security: []
paths:
  /calculations:
    post:
      tags:
        - Tax Calculations
      summary: Calculate Tax for Invoice
      description: Calculate tax for an invoice based on the provided request data.
      operationId: calculate_invoice_tax_calculations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCalculationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCalculationResponse'
        '422':
          description: Validation Error - Invalid input data
          content:
            application/json:
              schema:
                properties:
                  detail:
                    items:
                      properties:
                        type:
                          type: string
                        loc:
                          items:
                            type: string
                          type: array
                        msg:
                          type: string
                        input:
                          oneOf:
                            - type: string
                            - type: number
                            - type: boolean
                            - type: 'null'
                      type: object
                    type: array
                type: object
              example:
                detail:
                  - type: string_type
                    loc:
                      - body
                      - line_items
                      - 0
                      - quantity
                    msg: Input should be a valid string
                    input: 1
        '429':
          description: Rate limit exceeded. Try again later.
          headers:
            Retry-After:
              schema:
                type: string
              description: Time in seconds until the rate limit resets
            X-RateLimit-Limit:
              schema:
                type: string
              description: The rate limit ceiling for the given request
            X-RateLimit-Remaining:
              schema:
                type: string
              description: The number of requests remaining in the time window
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                    example: Rate limit exceeded
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
              example: Internal Server Error
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    CreateCalculationRequest:
      properties:
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: >-
            The currency of the transaction. Defaults to `USD`. The currency
            must be a valid ISO 4217 currency code.
          default: USD
          examples:
            - USD
        discount_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Discount Amount
          description: >-
            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.
          examples:
            - '100'
            - '1002'
        vendor_discount_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Vendor Discount Amount
          description: >-
            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.
          examples:
            - '100'
            - '1002'
        transaction_date:
          type: string
          format: date-time
          title: Transaction Date
          description: >-
            Date and time for the tax calculation. Timezone is required for
            better accuracy. Use the [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601) format. e.g:
            `2024-03-15T12:00:00Z`. If not provided, the current UTC date and
            time will be used.
          examples:
            - '2024-03-15T12:00:00Z'
        line_items:
          anyOf:
            - items:
                $ref: '#/components/schemas/LineItem-Input'
              type: array
            - type: 'null'
          title: Line Items
          description: >-
            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.
          examples:
            - - 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'
      additionalProperties: false
      type: object
      title: CreateCalculationRequest
      description: Create calculation request model.
    CreateCalculationResponse:
      properties:
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: >-
            Three-letter currency code. Values are limited to valid ISO 4217
            currency codes. e.g: `USD`
          default: USD
          examples:
            - USD
        tax_amount:
          type: string
          title: Tax Amount
          description: >-
            Total tax amount due, expressed in the smallest unit of currency for
            the invoice.e.g: `"2999"`, which for a USD invoice means $29.99
          examples:
            - '2999'
        line_items:
          items:
            $ref: '#/components/schemas/LineItemTaxes'
          type: array
          title: Line Items
          description: List of line items for the invoice
      additionalProperties: false
      type: object
      required:
        - tax_amount
        - line_items
      title: CreateCalculationResponse
      description: Response model containing the calculated tax details for an invoice.
    LineItem-Input:
      properties:
        customer:
          anyOf:
            - $ref: '#/components/schemas/CustomerData-Input'
            - type: 'null'
          description: >-
            Customer details for the line item. E.g: `{'address': {'line1': '123
            Main St', 'city': 'Anytown', 'state': 'CA', 'postal_code': '12345'},
            'preset': {'id': 'cust_123', 'source': 'stripe'}}`
        fulfillment:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentData-Input'
            - type: 'null'
          description: >-
            Fulfillment details for the line item. E.g: `{'address': {'line1':
            '123 Main St', 'city': 'Anytown', 'state': 'CA', 'postal_code':
            '12345'}, 'preset': {'id': 'ful_123', 'source': 'taxwire'}}`
        id:
          type: string
          minLength: 1
          title: Id
          description: >-
            Unique identifier for the line item, within the invoice /
            transaction. If not provided, an ID will be generated.
          examples:
            - item_123
        product:
          anyOf:
            - $ref: '#/components/schemas/ProductData-Input'
            - type: 'null'
          description: >-
            Product details for the line item. E.g: `{'address': {'line1': '123
            Main St', 'city': 'Anytown', 'state': 'CA', 'postal_code': '12345'},
            'tax_attributes':
            ['DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED']}`
        quantity:
          type: string
          title: Quantity
          description: >-
            Quantity of items. Decimal string to allow fractional quantities.
            Fractional quantities allow to express quantities like 1.5
            liters.e.g: `"1"`, `"1.5"`, `"0.75"`
          examples:
            - '1'
            - '1.5'
        seller:
          anyOf:
            - $ref: '#/components/schemas/SellerData-Input'
            - type: 'null'
          description: >-
            Seller details for the line item. E.g: `{'address': {'line1': '123
            Main St', 'city': 'Anytown', 'state': 'CA', 'postal_code': '12345'},
            'preset': {'id': 'org_123', 'source': 'taxwire'}}`
        unit_price:
          type: string
          title: Unit Price
          description: >-
            The price per unit of the item. Decimal value expressed as a string
            in order to support fractional values. `'1.0'` or `'1'` will result
            to `1.0`. (For example you can express a cost of $0.0000001/min as
            '0.0001' cents per minute) 

            The price is always expressed in the currency of the transaction.
            Unit prices are expressed in denominations of the smallest unit of
            the currency, such as cents for USD. e.g: `'100'` is equivalent to
            `$1.00` 
          examples:
            - '100'
            - '1002'
        discount_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Discount Amount
          description: >-
            Amount of discount applied to the line item. 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.
          examples:
            - '100'
            - '1002'
        vendor_discount_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Vendor Discount Amount
          description: >-
            Amount of discount applied to the vendor of the line item. 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 line item. 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.
          examples:
            - '100'
            - '1002'
        discounts:
          anyOf:
            - items:
                $ref: '#/components/schemas/LineItemDiscount'
              type: array
            - type: 'null'
          title: Discounts
          description: >-
            List of individual discounts applied to the line item. Cannot be
            used together with `discount_amount`. Each discount must have a
            unique `id` and an `amount`.
          examples:
            - - amount: '40'
                id: 1/discount/1
              - amount: '10'
                id: 1/discount/2
      additionalProperties: false
      type: object
      required:
        - quantity
        - unit_price
      title: LineItem
      description: A LineItem represents an individual item in an invoice or a transaction.
    LineItemTaxes:
      properties:
        id:
          type: string
          title: Id
          description: Line item ID
        tax_amount:
          type: string
          title: Tax Amount
          description: Total tax amount
        tax_amount_before_discounts:
          anyOf:
            - type: string
            - type: 'null'
          title: Tax Amount Before Discounts
          description: >-
            Tax amount before discount taxes are applied. Equal to tax_amount -
            sum of all discount tax_amounts. Only present when discounts are
            applied.
        discounts:
          anyOf:
            - items:
                $ref: '#/components/schemas/LineItemDiscountTaxes'
              type: array
            - type: 'null'
          title: Discounts
          description: List of tax amounts for each discount.
        taxes:
          items:
            $ref: '#/components/schemas/TaxItem'
          type: array
          title: Taxes
          description: List of tax items
      additionalProperties: false
      type: object
      required:
        - id
        - tax_amount
        - taxes
      title: LineItemTaxes
      description: Line item taxes model.
    CustomerData-Input:
      properties:
        address:
          anyOf:
            - $ref: '#/components/schemas/LocationInput-Input'
            - type: 'null'
          description: The address of the customer.
        preset:
          anyOf:
            - $ref: '#/components/schemas/Preset'
            - type: 'null'
          description: >-
            🏗️ **Coming soon** 🏗️ 

            The [`Preset`
            model](https://apidocs.taxwire.com/api-reference/presets) represents
            a saved tax context that can be applied to a line item. When
            ingesting data from a data source like Stripe, Taxwire creates tax
            presets that can be used in the tax calculation.
          examples:
            - id: cust_456
              source: taxwire
        tax_attributes:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Tax Attributes
          description: |-
            🏗️ **Coming soon** 🏗️ 
            Tax attributes adding tax context for the customer. e.g: `['B2B']`

             See the [Tax Attributes](https://taxwire.mintlify.app/api-reference/guides/tax_attributes) for more details.
        tax_ids:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxId'
              type: array
              maxItems: 10
            - type: 'null'
          title: Tax Ids
          description: >-
            Tax IDs associated with the customer. Used for purposes like
            applying VAT exemptions or the reverse charge mechanism.

            e.g: `[{'type': 'eu_vat', 'value': 'DE123456789', 'country': 'DE'}]`
      additionalProperties: false
      type: object
      title: CustomerData
      description: ''
    FulfillmentData-Input:
      properties:
        address:
          anyOf:
            - $ref: '#/components/schemas/LocationInput-Input'
            - type: 'null'
          description: The address of the fulfillment.
        tax_attributes:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Tax Attributes
          description: >-
            Tax attributes adding tax context for the fulfillment. e.g:
            `['MARKETPLACE']` to mark the line as marketplace-facilitated.When
            `MARKETPLACE` is present the seller-side tax engine produces zero
            tax for the line and the transaction is excluded from economic-nexus
            thresholds in jurisdictions with `excludes_marketplace_facilitator`.
            The API accepts this flag at face value without further validation;
            the consumer is responsible for asserting it correctly 

             See the [Tax Attributes](https://taxwire.mintlify.app/api-reference/guides/tax_attributes) for more details.
          examples:
            - - MARKETPLACE
        preset:
          anyOf:
            - $ref: '#/components/schemas/Preset'
            - type: 'null'
          description: >-
            🏗️ **Coming soon** 🏗️ 

            The preset for the fulfillment. e.g: `{'id': 'ful_123', 'source':
            'taxwire'}`

            A preset can contain tax attributes and a default addressthat will
            be used to calculate the tax for the fulfillment.
          examples:
            - id: ful_123
              source: taxwire
      additionalProperties: false
      type: object
      title: FulfillmentData
      description: ''
    ProductData-Input:
      properties:
        address:
          anyOf:
            - $ref: '#/components/schemas/LocationInput-Input'
            - type: 'null'
          description: >-
            The address of the product. Based on the type of good or service, it
            could be the service, lodging, property or the use location.e.g:
            `{'line1': '123 Main St', 'city': 'Anytown', 'state': 'CA',
            'postal_code': '12345'}`
        tax_attributes:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Tax Attributes
          description: >-
            Tax attributes adding tax context for the product. e.g:
            `['DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED']`

             See the [Tax Attributes](https://taxwire.mintlify.app/api-reference/guides/tax_attributes) for more details.
        preset:
          anyOf:
            - $ref: '#/components/schemas/Preset'
            - type: 'null'
          description: >-
            The preset for the product. e.g: `{'id': 'prod_123', 'source':
            'taxwire'}`

            A preset can contain tax attributes and a default addressthat will
            be used to calculate the tax for the product.
          examples:
            - id: prod_123
              source: taxwire
      additionalProperties: false
      type: object
      title: ProductData
      description: ''
    SellerData-Input:
      properties:
        address:
          anyOf:
            - $ref: '#/components/schemas/LocationInput-Input'
            - type: 'null'
          description: >-
            The address of the seller. It could also be the supply location.e.g:
            `{'line1': '123 Main St', 'city': 'Anytown', 'state': 'CA',
            'postal_code': '12345'}`
        tax_attributes:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Tax Attributes
          description: |-
            🏗️ **Coming soon** 🏗️ 
            Tax attributes adding tax context for the seller. e.g: `['B2B']`

             See the [Tax Attributes](https://taxwire.mintlify.app/api-reference/guides/tax_attributes) for more details.
        preset:
          anyOf:
            - $ref: '#/components/schemas/Preset'
            - type: 'null'
          description: >-
            🏗️ **Coming soon** 🏗️ 

            The preset for the seller. e.g: `{'id': 'org_123', 'source':
            'taxwire'}`

            A preset can contain tax attributes and a default addressthat will
            be used to calculate the tax for the seller.
          examples:
            - id: org_123
              source: taxwire
        tax_ids:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxId'
              type: array
              maxItems: 10
            - type: 'null'
          title: Tax Ids
          description: >-
            Tax IDs associated with the seller. Used for purposes like applying
            VAT exemptions or the reverse charge mechanism.

            e.g: `[{'type': 'eu_vat', 'value': 'DE123456789', 'country': 'DE'}]`
      additionalProperties: false
      type: object
      title: SellerData
      description: ''
    LineItemDiscount:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: >-
            Unique identifier for the discount. Must be unique across all line
            items in the transaction.
          examples:
            - disc_123
        amount:
          type: string
          title: Amount
          description: >-
            Amount of the discount. Expressed in the smallest unit of currency.
            e.g: `"100"` would be 100 cents or $1.00 in a USD transaction.
          examples:
            - '100'
            - '50'
      additionalProperties: false
      type: object
      required:
        - id
        - amount
      title: LineItemDiscount
      description: A discount applied to a line item.
    LineItemDiscountTaxes:
      properties:
        id:
          type: string
          title: Id
          description: Identifier for the discount.
          examples:
            - disc_123
        tax_amount_reduction:
          type: string
          title: Tax Amount Reduction
          description: >-
            Tax amount reduced by this discount. Expressed in the smallest unit
            of currency.
          examples:
            - '400'
            - '100'
      additionalProperties: false
      type: object
      required:
        - id
        - tax_amount_reduction
      title: LineItemDiscountTaxes
      description: Tax details for a discount on a line item.
    TaxItem:
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
          description: Name of the tax calculation
          examples:
            - County Transportation Fund
        rule_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Rule Name
          description: Name of the tax rule applied
          examples:
            - Clothing taxability rule
        jurisdiction_name:
          type: string
          title: Jurisdiction Name
          description: Name of the tax jurisdiction
          examples:
            - California
        jurisdiction_type:
          type: string
          title: Jurisdiction Type
          description: Type of jurisdiction (e.g., state, county, city)
          examples:
            - state
        tax_amount:
          type: string
          title: Tax Amount
          description: >-
            Amount of tax due in the transaction currency. Expressed as a
            decimal value to capture fractional amounts. Amount is expressed in
            denominations of the smallest unit of the currency, such as cents
            for USD. e.g: `"134"` would be 134 cents or 1.34 dollars in a USD
            transaction
          examples:
            - '10'
            - '1.03'
        taxable_base:
          type: string
          title: Taxable Base
          description: Base amount of the tax
          default: '0'
          examples:
            - '100'
            - '100.00'
        tax_rate:
          type: string
          title: Tax Rate
          description: Rate of tax applied
          default: '0'
          examples:
            - '0.05'
            - '1.03'
        tax_type:
          type: string
          title: Tax Type
          description: Type of tax imposition
          examples:
            - California District Transaction Tax
        is_registered:
          type: boolean
          title: Is Registered
          description: Whether the tax is in a registered jurisdiction
          examples:
            - true
            - false
      additionalProperties: false
      type: object
      required:
        - detail
        - jurisdiction_name
        - jurisdiction_type
        - tax_amount
        - tax_type
        - is_registered
      title: TaxItem
      description: TaxItems contain detailed tax calculation data.
    LocationInput-Input:
      properties:
        line1:
          anyOf:
            - type: string
            - type: 'null'
          title: Line1
        line2:
          anyOf:
            - type: string
            - type: 'null'
          title: Line2
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        latitude:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Latitude
        longitude:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Longitude
      type: object
      title: LocationInput
      description: Location input type.
    Preset:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the tax preset from the source
          examples:
            - prd_123
        source:
          type: string
          enum:
            - business_central
            - campfire
            - monetizenow
            - netsuite
            - quickbooks
            - rillet
            - shopify
            - stripe
            - taxwire
            - xero
          title: Source
          description: Source of the tax preset
          default: taxwire
      additionalProperties: false
      type: object
      required:
        - id
      title: Preset
      description: ''
    TaxId:
      properties:
        type:
          anyOf:
            - $ref: '#/components/schemas/TaxIdType'
            - type: 'null'
          description: Type of the tax ID.
          examples:
            - eu_vat
            - us_ein
            - gb_vat
            - ca_gst
            - au_abn
        value:
          type: string
          title: Value
          description: The value of the tax ID.
          examples:
            - DE123456789
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: >-
            Optional ISO 3166-1 alpha-2 country code associated with the tax
            ID. 
          examples:
            - DE
            - US
            - null
      additionalProperties: false
      type: object
      required:
        - value
      title: TaxId
      description: ''
    TaxIdType:
      type: string
      enum:
        - au_abn
        - au_arn
        - ca_gst
        - ca_pst
        - ca_qst
        - eu_vat
        - eu_oss_vat
        - gb_vat
        - us_ein
      title: TaxIdType
      description: Enumeration for supported tax ID types.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer

````