Appearance
What a call costs
Every provider call records what it cost, at the moment it happens.
For changing a rate, see Provider rates. This page is about how the number gets onto a run and what it can and cannot tell you.
Priced at write time
Cost is written onto the ProviderFetchRun when the run is recorded, and never re-derived on read.
Why not calculate it when asked
Re-deriving would silently re-price every historical run the next time a rate changed. A run has to keep what it was actually charged, and cost_rate_effective_on records which rate priced it.
An unknown price is nil, never zero
Several checks are not priced at all: Focal screening, Wathq GOSI, Wathq related registrations, Elm digital ID, and everything Sijilat. Their cost is unknown.
That is deliberately distinct from the checks that genuinely cost nothing — portfolio linkage, the website scan and domain intelligence call no biller, so their 0.00 is a fact rather than an absence.
| Basis | Amount | Meaning |
|---|---|---|
positive_inquiry | > 0 | The rate for a call that answered |
negative_inquiry | > 0 | Billed for a provider error |
no_provider_call | 0.00 | Nothing was sent — a reused result |
no_external_cost | 0.00 | No biller exists for this check |
no_published_rate | nil | Nothing prices this service |
unpriced_failure | nil | It failed in a way no rate covers |
run_incomplete | nil | The call has not finished |
rate_not_declared | nil | Nobody has put this call on a card |
A check constraint in Postgres enforces the pairing: a free basis must carry 0, a priced basis must carry more than 0, an unknown basis must carry NULL. Neither may borrow the other's value.
The failure this prevents
A total that treated unknown prices as free would understate the cost of every merchant it touched. That is the same lie as a screening reporting "clear" because nobody looked — see the principle.
Failed calls are not free
Watheq bills a flat 0.25 SAR for a negative inquiry — an error 400 or 404. So a registration that came back not-found still cost money, and a report counting only successful calls would understate every merchant whose lookup missed.
The note is about the biller, not the service: a 404 from Wathq GOSI is billed 0.25 even though its positive rate is unknown.
Only 400 and 404 are treated this way. Any other failure — a 500, a timeout, a missing API key, a request that never left the building — is unknown rather than free, because nothing says otherwise and guessing zero is the mistake.
Reused results cost nothing
A reused run answers from a call already made and paid for. Charging the full rate again would invent an invoice; charging nothing is the truth about this run, recorded as no_provider_call.
Priced by subject
Elm charges by who is looked up: 3.96 SAR for a Saudi citizen, 3.12 for a resident. The rate is resolved from the person's normalised identifier type, so an alias (iqama, nin) prices the same as its canonical form.
An identifier type matching neither — a passport, a GCC ID, a Bahraini CPR — prices as unknown rather than falling back to either number.
Keyed on the call, not the check
Rates are keyed on (provider_key, fetch_type) — what the resolver writes onto the run — rather than on check type. One check type can reach two billers: commercial_registration goes to Watheq in Saudi Arabia and Sijilat in Bahrain, and only one of them is on the sheet.
Totalling a merchant
The entity page's Cost of checks section counts every run for the merchant, including retries and failures, because a retry is a second invoice.
It sums only the priced ones, and reports how many it could not price:
4 of 11 provider calls have no published rate, so this total is a floor and not the whole cost.
The caveat travels with the number rather than sitting in a footnote. A bare total is believed, and this one is wrong in the reassuring direction.
An entity with no calls yet shows a neutral No calls yet, not a green 0.00 SAR. A reassuring zero for something nobody ran is the same mistake one column over.