Life of a lookup
One sales-tax lookup from a checkout: the free coverage check, the keyed call, the answer with its Sources and times, and the one billed hit.
A lookup asks a Dataset what is true of one key. This chapter follows one call from Fernway Goods' checkout to Ratebook, on the customer's plane: api.ratebook.dev, with a key from Ratebook's Portal.
Covered first
Before it charges a card, the checkout asks whether the address is in coverage. The coverage check is a HEAD request on the same lookup, and it charges nothing.
curl -I "https:The answer says the address is covered and what the lookup costs. An address outside coverage gets the same answer before any money moves. Coverage covers the map behind it.
The call
The checkout sends the lookup with its live key, which begins ratebook_sk_live_.
curl "https:The answer is every jurisdiction that taxes the address: the state, the county, the city and a transit district. Each carries its rate, its share of the total, its effective date and the authority that set it.
Every value with its origin
Each value names its Source and three times: when the rate took effect, when the authority published it, and when Ratebook last read it. A checkout that files returns keeps those with the order, and its auditor reads the same answer a year later.
| Field | Answers |
|---|---|
observedAt | When the rate was true |
publishedAt | When the Source published it |
refreshedAt | When the Dataset last read that Source |
Provenance has every field.
Counted once
The Meter counts the lookup as one billed hit. The same address again inside 24 hours counts once, so a checkout that retries or re-renders pays for one answer.
A miss returns an empty result, not an error, and counts as a free miss. The Portal's usage view splits billed hits from free misses, so Fernway Goods sees what it paid for.
On the builder's side
Ratebook's founder reads the same call from the builder's plane, at api.sb/ with the startup-builder package: the Action, its cost and the Meter Entry. The customer's plane never shows api.sb, and the builder's never needs the customer's key.
A year later
The rate changes on 2027-01-01, and Ratebook's daily refresh records the new value beside the old one. A lookup with at set to the order's date returns the rate as it stood then. As-of reads covers reading the past.
Next
The lifecycle page follows the Dataset itself, from its file to its retirement.