Jurisdiction Tax Breakdown

Every taxable item and shipping fee in a transaction response includes a jurisdiction_tax_breakdown object. It shows exactly how the tax was split across each tax authority - state, county, city, and so on - along with the rate, taxable base, and amount due at each level.

This is the primary field for tax reporting, filing preparation, and audit trails.

Structure

jurisdiction_tax_breakdown is a dict[str, JurisdictionTaxDetail]. Each key is a jurisdiction level string. The value carries all the monetary and metadata details for that level.

Example response (US Sales Tax)

{
  "jurisdiction_tax_breakdown": {
    "state": {
      "jurisdiction_type": "state",
      "jurisdiction_name": "California",
      "reporting_code": "CA",
      "tax_type": "sales_tax",
      "tax_rate": "0.060000",
      "taxable_amount": "100.000000",
      "non_taxable_amount": "0.000000",
      "tax_due": "6.000000",
      "gross_amount": "100.00"
    },
    "county": {
      "jurisdiction_type": "county",
      "jurisdiction_name": "Los Angeles County",
      "reporting_code": "LA",
      "tax_type": "sales_tax",
      "tax_rate": "0.010000",
      "taxable_amount": "100.000000",
      "non_taxable_amount": "0.000000",
      "tax_due": "1.000000",
      "gross_amount": "100.00"
    },
    "city": {
      "jurisdiction_type": "city",
      "jurisdiction_name": "Los Angeles",
      "reporting_code": "LOS_ANGELES",
      "tax_type": "sales_tax",
      "tax_rate": "0.012500",
      "taxable_amount": "100.000000",
      "non_taxable_amount": "0.000000",
      "tax_due": "1.250000",
      "gross_amount": "100.00"
    }
  }
}

Field Reference

Field	Type	Description
`jurisdiction_type`	`string`	Jurisdiction level key - matches the dict key (e.g., `"state"`, `"county"`)
`jurisdiction_name`	`string \| null`	Human-readable name of the jurisdiction (e.g., `"California"`, `"Los Angeles County"`)
`reporting_code`	`string \| null`	Code used for tax filing and reporting for this jurisdiction
`tax_type`	`string \| null`	Type of tax applied at this level (e.g., `"sales_tax"`)
`tax_rate`	`decimal`	Rate applied at this jurisdiction level (6dp precision)
`taxable_amount`	`decimal`	Portion of the line amount subject to tax at this level
`non_taxable_amount`	`decimal`	Portion of the line amount not subject to tax at this level
`tax_due`	`decimal`	Tax calculated: `tax_rate × taxable_amount` (6dp, ROUND_HALF_UP)
`gross_amount`	`decimal`	Pre-discount line total (`total_price`)
`filing_taxable_jurisdiction_id`	`uuid \| null`	Internal ID linking this entry to the filing jurisdiction record
`transaction_type_id`	`uuid \| null`	Internal transaction type rule ID (used for VAT/GT determination)
`transaction_type_rule_id`	`uuid \| null`	Internal rule ID for this jurisdiction's transaction type classification

Jurisdiction Levels

US Sales Tax

Key	Meaning
`state`	State-level rate
`county`	County-level rate
`city`	City/municipality rate
`mta`	Metropolitan Transit Authority rate
`spd`	Special Purpose District rate

Only levels with a non-zero rate appear in the breakdown. A transaction in a jurisdiction with only state and county rates will have exactly two entries.

Global Tax (VAT / GST)

Key	Meaning
`country`	Country-level rate
`federal`	Federal rate
`region`	Regional rate
`provincial`	Provincial rate
`state`	State-level rate

Manual rate fallback

When manual_sales_tax_rate is set and no engine rates are found for the jurisdiction, the breakdown contains a single "combined" entry:

Key	Meaning
`combined`	Blended manual rate, no jurisdiction breakdown available

See the Manual Tax Rates guide for details on how the breakdown is populated when a manual rate is combined with resolved jurisdiction rates.

Partial Taxability

Some product classifications are only partially taxable (e.g., a product where 60% of the price is taxable). In these cases:

taxable_amount is total_price_after_discount × taxable_base
non_taxable_amount is the remainder
tax_due = tax_rate × taxable_amount

The taxable_base fraction comes from the product classification for the item's tax_code.

Exempt Items

Items that are fully exempt still receive a jurisdiction_tax_breakdown when the engine can resolve rates - all monetary values are zeroed out:

{
  "jurisdiction_tax_breakdown": {
    "state": {
      "jurisdiction_type": "state",
      "tax_rate": "0.000000",
      "taxable_amount": "0.000000",
      "non_taxable_amount": "100.000000",
      "tax_due": "0.000000",
      "gross_amount": "100.00"
    }
  }
}

This preserves the jurisdiction structure for reporting even when no tax is collected. is_exempt: true and the taxability_reason field indicate the exemption applied.

Tax-Inclusive Pricing

When is_tax_inclusive: true, the engine extracts the pre-tax base before calculating each jurisdiction's taxable_amount and tax_due:

pre_tax_base = total_price_after_discount ÷ (1 + effective_combined_rate)

Each jurisdiction's taxable_amount and tax_due are computed from pre_tax_base. The gross_amount remains the submitted total_price.

Precision

All tax_due values are quantized to 6 decimal places using ROUND_HALF_UP. The sum of all tax_due values in the breakdown equals tax.total_tax for the item (also 6dp).

Manual Tax Rates

Complyt → Abacus Tax Engine Migration