Flovvy Receipts API — Overview

A photo of a receipt in, the data as JSON out. Your system sends the photo; Flovvy returns the merchant, date, currency, totals and every line of the receipt, with quantity, weight, unit and price per kilo or litre. Plus a check: do the lines, with the printed tax and discounts, add up exactly to the printed total? (reconciled).

It is the same reading engine as the Flovvy app. Data stays in the European Union.

What you get from us

• The API address.
• A test key (flv_test_…): free. It does not really read photos: it always answers with the same example receipt. Developers use it to build and test the integration.
• A live key (flv_live_…): reads real receipts and uses credits.
• This manual: the full technical guide for developers is the developer guide. The formal contract (OpenAPI) is openapi.json: import it into Postman or your development tools.

Keep keys secret and use them only from your servers, never inside a web page or an app: anyone could read them. If a key is lost or you want to change it, we give you a new one and the old one keeps working for up to 72 hours, so you can switch without interruption.

Credits

The service is prepaid: you buy credits, and each receipt read uses one credit.

• You pay for every reading we actually perform: the delivered receipt, and also a photo we read that turned out not to be a readable receipt, or has no total.
• The credit comes back automatically when the problem is on our side and the reading was not performed or not delivered in time (reading service unavailable, timeout). Every failed receipt says so: failure.credit_refunded.
• Sending the same request again (for example after a network error, with the same Idempotency-Key) costs nothing.
• Test keys never use credits.
• When the credits run out, the API answers 402 insufficient_credits and stores nothing. To top up, just write to us.
• Your balance is in every response (Flovvy-Credits-Remaining) and in GET /v1/balance.
• Pack credits never expire. With a monthly plan the month's credits are used first, and the unused ones expire at renewal (or at the end of the last paid month, if the plan ends).

Risk checks (on request)

On a receipt that was already read you can ask for risk checks: duplicates among your receipts, a payment that does not match (amount, date, merchant), a photo that was edited or declares it was generated with AI, totals that do not add up. The answer is a list of signals with a risk level: they tell you what to look at, they are not a verdict. They use no credits. Details in Risk checks.

Getting started

To see it at work without writing code there is the try page: paste the key, choose a photo of a receipt and see the result.

1. The developer integrates the API with the test key (quick start in section 1 of the developer guide).
2. When it works, they switch to the live key: nothing else changes.
3. Each receipt usually arrives in a few seconds. If our AI provider is temporarily busy, the receipt is retried automatically and can take a few minutes.

How long we keep data

• Photos are deleted 7 days after they are sent.
• Receipts (the result) are deleted 90 days after they are sent: store the results you need in your systems.
• The credit history is kept, without the receipt content.
• Receipts we misread (failed, or totals that don't add up) may be kept up to 12 months to improve the reading, unless you opt out (in the console, Team & account → Documents); never those in the health category, never shown to other customers.

Support

Write to us with the Flovvy-Request-Id of the call (it is in every response) and, if there is one, the receipt id (rcp_…). With these two we can find exactly what happened. Never send us your API key.