Effective dates & versioning

Two different clocks: when a rule applies, and when we knew about it.

Effective dates — when a rule applies

Every version has effective_from and effective_to. When you pass a pay_date, you get the version whose window contains that date. A mid-year rate change is simply two versions with adjacent windows, so a July payroll and a December payroll get different answers without any extra work on your side.

Versions — what we published

Published versions are immutable. When a figure is corrected or a state publishes a revision, we publish a new version and mark the old one superseded. The version number goes up and version.superseded_at is set on the old one. Store version.id with each payroll you run and you can always show exactly which rule you used.

as_of — replaying the past

On Growth and above, pass as_of to ask what the API would have answered at a past moment. This is how you reproduce last quarter's numbers exactly, even if a correction was published since.

# What did we tell you on 30 June about a 15 May paycheck?
curl "https://tax-api-dev.itensiahr.com/v1/rates/lookup?work_state=OR&pay_date=2025-05-15&as_of=2025-06-30T23:59:59Z" \
  -H "Authorization: Bearer $ITX_API_KEY"

API versioning

The current API version is 2026-10-01, returned in meta.api_version. Within /v1 we only make additive changes: new endpoints, new optional parameters and new fields. Ignore fields you don't recognise. Breaking changes would ship under a new path with advance notice.