What a billed scan is¶

1¢ per document. Same price for everyone — from 1 to 100 million documents.

One credit is one US cent, and one credit buys the recognition of one document. That is the whole price list. No seats, no minimums, no negotiated rate.

The interesting question is not what a document costs. It is which calls count as a document, and that is a rule rather than a judgement.

The predicate¶

A call is charged when the document type was determined and at least one of three kinds of evidence came out of it.

The evidence is any one of three things. A machine-readable zone whose check digits pass, five or more fields read from the visual zone, or a correctly decoded barcode. One of the three is enough, and a document that yields all three is still one credit.

Both halves are required. A page the engine could not identify is not a document, however much text came off it. A correctly identified document that yielded nothing is a recognition that produced no value.

The five-field floor is the least obvious of the three, and it is a threshold rather than a principle. A visual zone that gave up a surname and nothing else is not a recognized document. One that gave up a name, a number, two dates and a nationality is. Five is where those two cases separate on real documents.

Every response carries meta.billed, so your own records match ours without a reconciliation step. The figure it sums to is the one GET /v1/usage reports for the period.

Why billed and recognized are not the same word¶

The response carries two independent facts, and conflating them is the mistake this section exists to prevent.

meta.status says how far recognition got. meta.billed says whether the predicate above was satisfied. They usually agree, and the cases where they do not are real.

A scan can be recognized and not billed. The type was determined, one zone was read, and the engine called it a success. What came out was two visual fields, no zone and no barcode. The predicate is not met, and nothing is charged.

A scan can be billed and not recognized. The type was determined and a zone with valid check digits came out, and the engine declined to call the overall result a success. The caller has the document's contents; the credit is drawn.

Neither case is a defect. One word is about the process and the other is about what the process produced. A caller reconciling a bill reads the second one.

The five outcomes¶

Recognition ends in one of five states, and four of them are free.

A scan is recognized when the type was determined and the data came out. That is the state a charge normally goes with.

It is no document found when nothing document-shaped was located in the frame. A photograph of a desk, a finger over the lens, an empty page.

It is unreadable when a document was there and its type was determined, and no zone could be read off it. Glare, motion, a resolution too low for the print.

It is unsupported document when something was located whose type is not in the catalogue. Nothing about retrying helps; the document is not one the engine reads.

It is rejected when recognition ran to the end and the engine did not call the result a success.

A retry after a free outcome is a new call, and it is free again unless it produces the evidence. Nothing accumulates: a document photographed four times badly and once well costs one credit.

Reserved before, settled after¶

The charge is not applied at the end of a successful scan. It is held at the beginning and resolved at the end.

A credit is reserved before the engine is called. The hold is a real movement in the ledger, so the balance reflects it while the scan is running. Two requests cannot both spend the last credit.

When the result comes back, the hold is committed if the predicate is met and released if it is not. A commit that settles a hold moves no further money; the credit left the balance when the hold was placed.

If the engine fails or times out, the hold is released and the balance is untouched. The caller gets an error, and the failure costs nothing.

The order matters for the case that would otherwise be worst: an account with no credits. Because the reservation comes first, such a call is refused with 402 insufficient_credits before the image is sent for recognition. Nobody is charged for a call that could not run, and no recognition capacity is spent on a caller who could not have been served.

The same order is why a balance cannot go negative. The floor is not a check in the application that could be forgotten on some path. A database constraint refuses the entry that would take a balance below zero, so the overdraft has no code path at all.

What is never charged¶

Anything refused before the engine.

A bad key, a body over the ceiling, a rate limit, an unsupported media type, an exhausted allowance. All of them are decided in front of recognition, and none of them costs a credit.

Anything a sandbox key does.

Neither kind of sandbox key draws on a balance. The public one runs real recognition free within its allowance. An account's own sandbox key is answered from a fixed specimen and never reaches the Engine.

A replayed request.

A retry carrying an Idempotency-Key that has already been used returns the first result and charges nothing the second time. That is the whole reason the header exists.

A failure on our side.

An engine that could not be reached, a store that was away, an internal error. The hold is released, the balance is whole, and the error body says which it was.

Why the price is one number¶

A per-document price with no tiers is unusual enough to be worth explaining.

Volume pricing exists where volume changes a supplier's costs. Recognition does not work that way here: the hundred-thousandth document costs what the first one did, because each is one pass over one image.

A published single number also does something a negotiated one cannot. It can be compared, planned against and put in a spreadsheet before anybody talks to us. A developer costing an integration at two in the morning gets an exact answer.

The corollary is that there is nothing to ask for. No rate is available that is not on this page, and no volume unlocks one.

Where the free documents come from¶

A caller with no account has 10 free recognitions on the public sandbox key, counted per client. Past them the API answers registration_required, which is an invitation rather than a wall.

An account arrives with 20 free documents credited to its balance. They are ordinary credits, indistinguishable from bought ones once they are there.

After that, a balance is topped up and every billable document draws one credit from it. A credit is a cent and a document is a credit, so the balance is also the number of documents left. That is the only arithmetic a caller has to do.