Skip to navigation
AvaTax quickstart guides

Calculate sales tax

Turn an order into jurisdiction-accurate tax with a single call.

View as Markdown

Tax calculation happens through POST /api/v2/transactions/create. You describe the document — its type, addresses, and line items — and AvaTax returns tax for every applicable jurisdiction.

Document types

The type field controls whether a transaction is recorded.

TypeRecorded?Use it for
SalesOrderNoCart estimates and quotes
SalesInvoiceYesFinalized orders that feed reporting

Use SalesOrder while a customer is shopping, then create a SalesInvoice at checkout.

Request

POST
/api/v2/transactions/create
curl -X POST https://rest.avatax.com/api/v2/transactions/create \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json-patch+json" \
     -d '{
  "lines": [
    {
      "amount": 100,
      "number": "1",
      "quantity": 1,
      "taxCode": "PS081282",
      "itemCode": "Y0001",
      "description": "Yarn"
    }
  ],
  "date": "2026-07-06",
  "customerCode": "ABC",
  "type": "SalesInvoice",
  "companyCode": "DEFAULT",
  "purchaseOrderNo": "2026-07-06-001",
  "addresses": {
    "singleLocation": {
      "line1": "2000 Main Street",
      "city": "Irvine",
      "region": "CA",
      "country": "US",
      "postalCode": "92614"
    }
  },
  "commit": true,
  "currencyCode": "USD",
  "description": "Yarn"
}'
Try it

Line-level detail

Each entry in lines can carry its own item code, tax code, and amount. AvaTax maps itemCode to the tax rules you’ve configured, so a potted fern and a gift card on the same order are taxed correctly.

Multi-line order with a discount
{
  "type": "SalesInvoice",
  "companyCode": "GREENLEAF",
  "customerCode": "CUST-4021",
  "date": "2026-07-06",
  "discount": 5.00,
  "addresses": {
    "shipFrom": { "line1": "312 Nursery Row", "city": "Seattle", "region": "WA", "postalCode": "98101", "country": "US" },
    "shipTo":   { "line1": "88 Garden Ave", "city": "Denver", "region": "CO", "postalCode": "80202", "country": "US" }
  },
  "lines": [
    { "number": "1", "quantity": 3, "amount": 74.97, "itemCode": "FERN-06", "description": "Potted Boston fern", "discounted": true },
    { "number": "2", "quantity": 1, "amount": 24.00, "itemCode": "SOIL-01", "description": "Organic potting mix" }
  ]
}

Set discounted: true on the lines a document-level discount should apply to. AvaTax spreads the discount across those lines before calculating tax.

Response

The response echoes each line with its computed tax, plus a summary array breaking tax down by jurisdiction and tax type.

Response
{
  "id": 123456789,
  "code": "becc7b69-e05c-489a-95c7-52f0a0794099",
  "companyId": 12345,
  "date": "2026-07-06",
  "status": "Committed",
  "type": "SalesInvoice",
  "currencyCode": "USD",
  "exchangeRateCurrencyCode": "USD",
  "entityUseCode": "",
  "customerVendorCode": "ABC",
  "customerCode": "ABC",
  "exemptNo": "",
  "reconciled": true,
  "locationCode": "DEFAULT",
  "salespersonCode": "DEF",
  "taxOverrideType": "None",
  "taxOverrideAmount": 0,
  "taxOverrideReason": "",
  "totalAmount": 1000,
  "totalExempt": 0,
  "totalDiscount": 0,
  "totalTax": 62.5,
  "totalTaxable": 1000,
  "totalTaxCalculated": 62.5,
  "adjustmentReason": "NotAdjusted",
  "adjustmentDescription": "",
  "locked": false,
  "region": "CA",
  "country": "US",
  "version": 0,
  "originAddressId": 123456789,
  "destinationAddressId": 123456789,
  "exchangeRateEffectiveDate": "2026-07-06",
  "exchangeRate": 2,
  "isSellerImporterOfRecord": false,
  "description": "Yarn",
  "taxDate": "2026-07-06T00:00:00+00:00",
  "lines": [
    {
      "id": 123456789,
      "transactionId": 123456789,
      "lineNumber": "1",
      "boundaryOverrideId": 0,
      "entityUseCode": "",
      "description": "Yarn",
      "destinationAddressId": 12345,
      "originAddressId": 123456789,
      "discountAmount": 100,
      "discountTypeId": 0,
      "exemptAmount": 0,
      "exemptCertId": 0,
      "exemptNo": "",
      "isItemTaxable": true,
      "isSSTP": false,
      "itemCode": "116292",
      "lineAmount": 1000,
      "quantity": 1,
      "ref1": "Note: Deliver to Bob",
      "reportingDate": "2026-07-06",
      "revAccount": "",
      "sourcing": "Destination",
      "tax": 62.5,
      "taxableAmount": 1000,
      "taxCalculated": 62.5,
      "taxCode": "PS081282",
      "taxDate": "2026-07-06",
      "taxEngine": "",
      "taxOverrideType": "None",
      "taxOverrideAmount": 0,
      "taxOverrideReason": "",
      "taxIncluded": false,
      "details": [
        {
          "id": 123456789,
          "transactionLineId": 123456789,
          "transactionId": 123456789,
          "addressId": 12345,
          "country": "US",
          "region": "CA",
          "stateFIPS": "06",
          "exemptAmount": 0,
          "exemptReasonId": 4,
          "exemptRuleId": 0,
          "inState": false,
          "jurisCode": "06",
          "jurisName": "CALIFORNIA",
          "jurisdictionId": 5000531,
          "signatureCode": "AGAM",
          "stateAssignedNo": "",
          "jurisType": "STA",
          "nonTaxableAmount": 0,
          "nonTaxableRuleId": 0,
          "nonTaxableType": "BaseRule",
          "rate": 0.0625,
          "rateRuleId": 1321915,
          "rateSourceId": 3,
          "serCode": "",
          "sourcing": "Destination",
          "tax": 62.5,
          "taxableAmount": 1000,
          "taxType": "Sales",
          "taxName": "CA STATE TAX",
          "taxAuthorityTypeId": 45,
          "taxRegionId": 2127184,
          "taxCalculated": 62.5,
          "taxOverride": 0,
          "rateType": "General",
          "taxableUnits": 62.5,
          "nonTaxableUnits": 1000,
          "exemptUnits": 62.5,
          "reportingTaxableUnits": 125,
          "reportingNonTaxableUnits": 2000,
          "reportingExemptUnits": 125,
          "reportingTax": 125,
          "reportingTaxCalculated": 125,
          "recoverabilityPercentage": 1,
          "recoverableAmount": 62.5,
          "nonRecoverableAmount": 0,
          "vatCode": "",
          "granularDutyDetails": [
            {
              "amount": "105.00",
              "dutyType": "ImportDuty",
              "rate": "10.5"
            }
          ]
        }
      ],
      "vatNumberTypeId": 0,
      "recoverabilityPercentage": 1,
      "recoverableAmount": 62.5,
      "nonRecoverableAmount": 0
    }
  ],
  "addresses": [
    {
      "id": 0,
      "transactionId": 0,
      "boundaryLevel": "Address",
      "line1": "100 Ravine Lane Northeast #220",
      "city": "Bainbridge Island",
      "region": "WA",
      "postalCode": "98110",
      "country": "US",
      "taxRegionId": 0
    }
  ],
  "taxDetailsByTaxType": [
    {
      "taxType": "SalesAndUse",
      "totalTaxable": 100,
      "totalExempt": 0.05,
      "totalNonTaxable": 0,
      "totalTax": 0.625
    }
  ]
}

Exemptions

To exempt a line or document, pass an exemptionNo or an entityUseCode (for example, G for a government buyer). AvaTax validates the reason and zeroes out tax where the exemption applies.

Calculation is deterministic: the same document always yields the same tax. Persist the returned transaction code so you can commit, adjust, or void it later.