Excise Tax Order Diagnostics

darrin

— 3 min read

When an excise tax calculation doesn't match what was collected at checkout, the first question is always why. Which tax rules fired? What product data was used? Did the shipping address resolve to the right jurisdiction?

Order Diagnostics answers these questions by capturing a snapshot of everything that went into a tax calculation — the rules, the product data, the jurisdiction resolution — and making it available through the order lookup API.

What gets captured

Every time a real order is processed (a /calculate call that includes taxCollected), the system now builds a diagnostic context — a point-in-time record of the inputs and logic that produced the tax result. This happens automatically, regardless of feature flags.

The diagnostic context contains six sections:

rules — A map of every tax rule that was evaluated, keyed by jurisdiction rule ID. Each entry contains the full rule definition as it existed at calculation time.

products — A snapshot of each product in the transaction as the tax engine saw it: SKU, product ID, volume, wholesale price, retail price, vape system type, tags, and whether the product had missing data. Each product also includes the transaction-level pricing (unit sales price, discounted price, whether a discount was applied) and the list of rules that were applied to it with their calculated amounts.

skippedProducts — Products that were excluded from taxation and why. Reasons include tax exemptions (product-level, date-based, or customer-based) and missing product data errors.

jurisdictionResolution — Shows both the raw shipping address from the request and the resolved jurisdiction fields (country, region, county, locality) used for rule matching. This is the first place to look when a tax amount seems wrong for a given address.

customerExemption — Whether the customer was exempt from excise tax at the time of the order, and the exemption start timestamp if applicable.

transactionType — The transaction type used for the calculation (e.g., retail, wholesale).

How to retrieve diagnostics for an order

  1. Go to HQ > Internal APIs (/hq/api-docs) and open Excise Tax Order Lookup
  2. Expand GET /exciseTax/order/{orderId}
  3. Enter the order ID and set the includeDiagnostics query param to true
  4. Execute — the response will include diagnosticContext alongside the order data

Direct link: /hq/api-docs/excise-tax-order

Add ?includeDiagnostics=true to the existing order lookup endpoint:

GET /api/exciseTax/order/{orderId}?includeDiagnostics=true

The response includes the standard order data plus a diagnosticContext field:

{
  "content": {
    "order": {
      "orderId": "ORDER-123",
      "exciseTaxCollected": "5.50",
      "transactionLines": [...],
      "products": {...},
      "shippingLocation": {...}
    },
    "diagnosticContext": {
      "rules": {
        "US-CA-vape-ml": {
          "rate": 0.12,
          "rateType": "perMl",
          "jurisdictionType": "state"
        }
      },
      "products": [
        {
          "sku": "VAPE-001",
          "productId": "excise_product_1",
          "volumeInMl": 30,
          "retailPrice": 80,
          "tags": ["hasNicotine"],
          "unitSalesPrice": "95.00",
          "unitDiscountedPrice": "85.50",
          "hasDiscount": true,
          "appliedRules": [
            {
              "ruleId": "US-CA-vape-ml",
              "jurisdictionType": "state",
              "unitTax": "3.60",
              "taxForQty": "7.20"
            }
          ]
        }
      ],
      "skippedProducts": [],
      "jurisdictionResolution": {
        "countryCode": "US",
        "regionCode": "CA",
        "county": null,
        "locality": "San Francisco",
        "input": {
          "countryCode": "US",
          "regionCode": "CA",
          "postalCode": "94102"
        }
      },
      "customerExemption": {
        "isExempt": false,
        "exemptionStartTimestamp": null
      },
      "transactionType": "retail"
    }
  },
  "metadata": {
    "status": 200,
    "version": "1.0.0"
  }
}

Without ?includeDiagnostics, the order endpoint behaves exactly as before — no diagnosticContext is returned.

How it works under the hood

When a real order is calculated, the diagnostic context is attached to the metric that the system already records for that order — either a collected metric (tax matched) or an error.incorrectCollection metric (tax mismatch). These metrics were already being written; now they carry the diagnostic payload too.

When you request diagnostics via the order API, the system looks up the metric for that order ID, extracts the diagnostic context from it, and includes it in the response. It checks collected first, then error.incorrectCollection, then falls back to calculated. If no diagnostics are found (e.g., the order predates this feature), the order returns normally without a diagnosticContext field.

Common debugging scenarios

Tax amount is wrong for a product:
Check diagnosticContext.products — find the product by SKU and look at appliedRules. Compare the rule's rate and rate type against the product's volume, wholesale price, or retail price to see how the tax was calculated. Check missingData to see if the product record was incomplete.

Tax is zero when it shouldn't be:
Check diagnosticContext.skippedProducts — the product may have been exempted. Common reasons include customer exemptions, date-based exemptions, or missing product data. Also check customerExemption.isExempt.

Wrong jurisdiction applied:
Check diagnosticContext.jurisdictionResolution — compare input (what was sent) against the resolved fields (what was used for rule matching). If the region or county doesn't match expectations, the address resolution may need attention.

Product data looks stale:
The product snapshot in diagnostics reflects the product data at the time of the order. Compare it against current product data in the product catalog to see if fields have changed since the order was placed.

Read more