TaxLite API Documentation

Public endpoint. Returns a trial API key (40 calls, 7 days).

curl -X POST https://api.taxlite.io/api/keys/create-trial

curl -X POST https://api.taxlite.io/api/calculate \
  -H "Content-Type: application/json" \
  -H "x-company-key: tl_live_your_api_key" \
  -d '{
    "state_code": "CO",
    "city": "Denver",
    "zip_code": "80202",
    "address": "123 Main St",
    "taxable_base_cents": 10000
  }'

{
  "taxable_base_cents": 10000,
  "tax_amount_cents": 915,
  "total_amount_cents": 10915,
  "total_rate_dbps": 9150,
  "state_rate_dbps": 2900,
  "local_rate_dbps": 6250,
  "confidence": 1,
  "source": "POLYGON_DATABASE",
  "api_log_id": "abc123...",
  "calculation_id": "abc123...",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

curl -X POST https://api.taxlite.io/api/calculate \
  -H "Content-Type: application/json" \
  -H "x-company-key: tl_live_your_api_key" \
  -d '{
    "state_code": "CO",
    "city": "Denver",
    "zip_code": "80202",
    "address": "123 Main St",
    "taxable_base_cents": 10000
  }'

Auth: API key

Request body

Field	Description
state_code (required)	2-letter state code.
taxable_base_cents (required)	Integer cents. Example: 10000 = $100.00.
city (required*)	Either city or zip_code must be provided.
zip_code (required*)	Either city or zip_code must be provided.
address	Optional. If provided, PO Boxes are rejected.
lat, lng	Optional. If provided, skips geocoding (faster and less dependent on address parsing).

(required*) means “at least one of these is required.”

Response

Response shape (successful 200): taxable_base_cents, tax_amount_cents, total_amount_cents, total_rate_dbps, state_rate_dbps, local_rate_dbps, api_log_id, calculation_id, expires_at.
Usually present: confidence, source (omitted if unknown).

Auth: API key

Preferred (best UX): api_log_id-only

If you already called /api/calculate, you should record the sale by sending only api_log_id (alias: calculation_id). TaxLite will hydrate all filing context from logs.

Recommended fields

• api_log_id (or calculation_id)
• idempotency_key (prevents duplicate transactions on retries; unique per order/payment)
• event_id, payment_id (your identifiers)

Example (preferred)

{
  "event_id": "order-123",
  "payment_id": "pay-456",
  "idempotency_key": "order-123",
  "api_log_id": "abc123..."
}

Alias: you can also send calculation_id instead of api_log_id.

Manual fallback (no api_log_id)

This is an ops-only escape hatch. If you did not call /api/calculate, you can still record manually by providing the core fields. TaxLite will record money totals, but filing identifiers may be missing. This path triggers alerts so gaps get backfilled ASAP.

{
  "event_id": "order-123",
  "payment_id": "pay-456",
  "idempotency_key": "order-123",
  "state_code": "CO",
  "taxable_base_cents": 10000,
  "total_tax_cents": 915
}

Response

{
  "status": "ok",
  "tax_event_id": "uuid-or-null",
  "filing_payload_missing": false,
  "quote_mismatch": false,
  "warnings": []
}

Auth: API key

Mental model: TaxLite stores refunds as a negative mirror row in tax_events. That means reports, rollups, and filing exports remain correct by summing events.

Required fields

• original_tax_event_id: the tax_events.id of the sale you are refunding
• refund_id: your refund identifier (used for idempotency; unique per company)
• refund_taxable_base_cents: refund base magnitude (positive integer)

Optional fields

• refund_total_tax_cents: refund tax magnitude (positive integer). If omitted, TaxLite prorates from the original effective rate.
• apply_to_original_period: boolean (default false). If true, the refund is applied to the original sale month (restatement).
• refund_timestamp: ISO string or unix seconds/ms. Default: now.

Example

{
  "original_tax_event_id": "uuid-of-sale",
  "refund_id": "rf_123",
  "refund_taxable_base_cents": 5000,
  "refund_total_tax_cents": 412,
  "apply_to_original_period": false
}

Response

{
  "status": "ok",
  "original_tax_event_id": "uuid-of-sale",
  "refund_tax_event_id": "uuid-of-refund",
  "refund_id": "rf_123"
}

Auth: API key. Returns state totals for a date range.

• start=YYYY-MM-DD (optional)
• end=YYYY-MM-DD (optional)
• state=IL (optional)

Auth: session JWT. Returns bucket totals for one state.

• state=IL (required)
• start=YYYY-MM-DD (optional)
• end=YYYY-MM-DD (optional)
• filing_category=general_sales (optional, default: general_sales)

Buckets contain bucket_key, identifiers, and money totals. The identifier keys are state-specific.

Auth: session JWT. Returns a file download (CSV/XLSX/NDJSON).

Filing export

{
  "format": "csv",
  "report_type": "filing_csv",
  "state_code": "ALL",
  "filing_category": "general_sales",
  "start": "2025-12-01",
  "end": "2025-12-31"
}

state_code supports "IL" for a single state, or "ALL"/"*" for an all-states export. If no data exists, this endpoint returns 404 with {"error":"No filing_payload data found for export"}.