Calculations

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 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 create the transaction to persist it for filing.

Request

POST /calculations

transaction

transaction object

required

The transaction object to calculate taxes for. See the Transactions page for the full schema.

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"
      }
    ]
  }'

Response

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

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.

{
  "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
    }
  ]
}

{
    "code": "BAD_REQUEST",
    "message": "Input validation failed",
    "issues": [
        {
            "code": "",
            "path": [],
            "message": ""
        }
    ]
}

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

CompaniesRetrieve company information associated with your API key.

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"
      }
    ]
  }'

{
  "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
    }
  ]
}

{
    "code": "BAD_REQUEST",
    "message": "Input validation failed",
    "issues": [
        {
            "code": "",
            "path": [],
            "message": ""
        }
    ]
}

​Calculate Tax

​Request

​Response

​Tax Breakdown Fields

Calculate Tax

Request

Response

Tax Breakdown Fields