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

# Calculations

> Calculate tax due on transactions in real-time.

Calculations are core to what the Zamp API provides. Given a transaction object, the Calculation endpoint returns the tax due along with a detailed breakdown of those taxes.

After collecting taxes, you should [create the transaction](/api-reference/transactions) to persist it for filing.

## Calculate Tax

This endpoint calculates taxes for a given transaction. It's intended to be used at transaction time to determine how much tax to collect. But once you've collected, you'll later want to make sure and [**<u>create the transaction</u>**](https://developer.zamp.com/api/transactions#create-a-transaction) to persist it for filing.

### Request

```json theme={null}
POST /calculations
```

<ParamField body="transaction" type="transaction object" required>
  The transaction object to calculate taxes for. See the [Transactions](/api-reference/transactions) page for the full schema.
</ParamField>

<RequestExample>
  ```json POST /calculations theme={null}
  curl -X POST https://api.zamp.com/calculations \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "123",
      "name": "INV-123",
      "transactedAt": "2023-07-01T00:00:00.000Z",
      "isResale": false,
      "discount": 2,
      "subtotal": 18,
      "shippingHandling": 5,
      "total": 23,
      "shipToAddress": {
        "line1": "120 SW 10TH AVE",
        "line2": null,
        "state": "KS",
        "city": "TOPEKA",
        "zip": "66612"
      },
      "lineItems": [
        {
          "id": "LI-123",
          "amount": 10,
          "quantity": 2,
          "discount": 0,
          "shippingHandling": 0,
          "productName": "The Ultimate Sampler",
          "productSku": "SAMPLER-100",
          "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
        }
      ]
    }'
  ```
</RequestExample>

### Response

The response includes the original transaction plus `taxDue` and a `taxes` array with the full jurisdiction breakdown.

<Note>
  Tax is itemized per jurisdiction (state, county, city) and split between the taxable base and shipping/handling, so a single line item can produce several `taxes` entries. The `taxDue` values across all entries sum to the top-level `taxDue`.
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "123",
    "name": "INV-123",
    "taxDue": 1.58,
    "taxes": [
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.S.20",
        "jurisdictionName": "KANSAS",
        "jurisdictionDivision": "STATE",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": null,
        "taxableAmount": 18,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.04,
        "taxDue": 0.72,
        "taxCollected": 0
      },
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.S.20",
        "jurisdictionName": "KANSAS",
        "jurisdictionDivision": "STATE",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": "SHIPPING_HANDLING",
        "taxableAmount": 5,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.04,
        "taxDue": 0.2,
        "taxCollected": 0
      },
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.C.177",
        "jurisdictionName": "SHAWNEE COUNTY",
        "jurisdictionDivision": "COUNTY",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": null,
        "taxableAmount": 18,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.0135,
        "taxDue": 0.243,
        "taxCollected": 0
      },
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.C.177",
        "jurisdictionName": "SHAWNEE COUNTY",
        "jurisdictionDivision": "COUNTY",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": "SHIPPING_HANDLING",
        "taxableAmount": 5,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.0135,
        "taxDue": 0.0675,
        "taxCollected": 0
      },
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.I.71000",
        "jurisdictionName": "TOPEKA CITY",
        "jurisdictionDivision": "CITY",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": null,
        "taxableAmount": 18,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.015,
        "taxDue": 0.27,
        "taxCollected": 0
      },
      {
        "lineItemId": "LI-123",
        "state": "KS",
        "sourcing": "INTER_DESTINATION",
        "jurisdictionCode": "KS.I.71000",
        "jurisdictionName": "TOPEKA CITY",
        "jurisdictionDivision": "CITY",
        "compositeCode": "SNTOP",
        "compositeName": "TOPEKA",
        "exceptionCode": "FOOD_SUPPLEMENTS",
        "ancillaryType": "SHIPPING_HANDLING",
        "taxableAmount": 5,
        "nontaxableAmount": 0,
        "excludedAmount": 0,
        "taxRate": 0.015,
        "taxDue": 0.075,
        "taxCollected": 0
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
      "code": "BAD_REQUEST",
      "message": "Input validation failed",
      "issues": [
          {
              "code": "",
              "path": [],
              "message": ""
          }
      ]
  }
  ```
</ResponseExample>

### Tax Breakdown Fields

| Field                  | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `lineItemId`           | Associated line item identifier                     |
| `state`                | State abbreviation                                  |
| `sourcing`             | Sourcing method (e.g., `INTER_DESTINATION`)         |
| `jurisdictionCode`     | Unique jurisdiction identifier                      |
| `jurisdictionName`     | Jurisdiction display name                           |
| `jurisdictionDivision` | Division type (`STATE`, `COUNTY`, `CITY`)           |
| `compositeCode`        | Composite jurisdiction code                         |
| `compositeName`        | Composite jurisdiction name                         |
| `exceptionCode`        | Tax exception classification                        |
| `ancillaryType`        | Additional type (e.g., `SHIPPING_HANDLING`, `null`) |
| `taxableAmount`        | Amount subject to taxation                          |
| `nontaxableAmount`     | Non-taxable portion                                 |
| `excludedAmount`       | Excluded amount                                     |
| `taxRate`              | Applicable tax rate (decimal)                       |
| `taxDue`               | Calculated tax obligation                           |
| `taxCollected`         | Amount already collected                            |