Manual Tax Rates

Abacus Tax Engine calculates tax rates automatically by resolving the jurisdiction from the transaction's shipping address and looking up the applicable rates. In some scenarios you may already have the correct rate from an authoritative external source - for example, from your ERP, a third-party tax data provider, or a rate that was locked in at the time of a prior quote.

For these cases, supply manual_sales_tax_rate on the line item or shipping fee. The engine applies this rate directly instead of the automatic rate, but the response follows exactly the same structure as a standard calculation.

For field definitions, see the Transactions API Reference.

How It Works

Set manual_sales_tax_rate to a decimal rate between 0 and 1 on any item or on shipping_fee:

{
  "name": "Laptop",
  "unit_price": "1000.00",
  "quantity": "1",
  "tax_code": "ELECTRONICS",
  "manual_sales_tax_rate": 0.0825
}

The engine computes tax_due = total_price_after_discount × manual_sales_tax_rate (or the tax-inclusive equivalent). The result is written into the standard tax summary and jurisdiction_tax_breakdown - no separate manual response fields exist.

tax_adjustments on the item will contain "manual_tax_rate_applied" to confirm the override ran.

{
  "shipping_fee": {
    "total_price": "9.99",
    "manual_sales_tax_rate": 0.05
  }
}

Response Structure

When the engine resolves jurisdiction rates

If the engine finds tax rates for the item's tax_code and shipping address, the manual rate overrides the monetary values while the jurisdiction structure is preserved. The total manual tax is apportioned across the engine's jurisdiction entries in proportion to their rate share. The taxable_amount is back-calculated as manual_total ÷ combined_engine_rate.

Example: $100 item, manual_sales_tax_rate: 0.05. Engine resolves state=6%, county=2% (combined=8%).

• Manual total = $100 × 0.05 = $5.00
• State share (6/8 = 75%) → tax_due: 3.750000
• County share (2/8 = 25%) → tax_due: 1.250000
• taxable_amount back-calculated = $5.00 ÷ 0.08 = $62.50

{
  "tax": {
    "total_tax": "5.000000",
    "effective_tax_rate": "0.050000"
  },
  "jurisdiction_tax_breakdown": {
    "state": {
      "jurisdiction_type": "state",
      "jurisdiction_name": "Example State",
      "tax_rate": "0.06",
      "taxable_amount": "62.500000",
      "non_taxable_amount": "0",
      "tax_due": "3.750000",
      "gross_amount": "100.00"
    },
    "county": {
      "jurisdiction_type": "county",
      "jurisdiction_name": "Example County",
      "tax_rate": "0.02",
      "taxable_amount": "62.500000",
      "non_taxable_amount": "0",
      "tax_due": "1.250000",
      "gross_amount": "100.00"
    }
  },
  "tax_adjustments": ["manual_tax_rate_applied"]
}

The tax_rate values in the breakdown reflect the underlying engine rates (not the manual rate). They are preserved for reporting purposes - only the monetary values (tax_due, taxable_amount) are replaced.

When no jurisdiction rates are found

If no tax rates are found for the item's tax code (or there is no resolvable shipping address), the engine creates a single "combined" jurisdiction entry:

{
  "tax": {
    "total_tax": "8.250000",
    "effective_tax_rate": "0.082500"
  },
  "jurisdiction_tax_breakdown": {
    "combined": {
      "jurisdiction_type": "combined",
      "tax_rate": "0.082500",
      "taxable_amount": "100.000000",
      "non_taxable_amount": "0",
      "tax_due": "8.250000",
      "gross_amount": "100.00"
    }
  },
  "tax_adjustments": ["manual_tax_rate_applied"]
}

Tax-Inclusive Pricing

When is_tax_inclusive: true, the engine extracts the tax from the submitted price rather than adding on top:

manual_total = price - (price ÷ (1 + manual_sales_tax_rate))

See the Tax-Inclusive Pricing guide for full details on inclusive transactions.

Exemptions and Manual Rates

An item with both an exemption_id/exemption_reason and a manual_sales_tax_rate is not exempt - the manual rate takes precedence and tax is applied. To suppress tax on an item, omit manual_sales_tax_rate.

Rate Validation

• manual_sales_tax_rate: decimal, 0 ≤ rate ≤ 1 (e.g., 0.0825 for 8.25%)
• A value of 0 is treated as no manual rate - automatic lookup applies