Flovvy Receipts API — v1

Send a photo of a receipt, get back structured JSON: merchant, date, currency, totals and every line — with quantity, weight, unit and price per unit — plus a check that the lines add up to the printed total.

• Contract (OpenAPI 3.1): openapi.json — import it into Postman, Insomnia or your code generator.
• Receipt schema version: 2026-10-15.
• Risk checks (duplicates, payment match, edited or AI-generated images) on request: section 9.
• Data stays in the EU.

Last updated 29 October 2026. The examples are real responses of the API.

1. Quick start

You receive from us:

export FLOVVY_BASE_URL="https://phxkxiktoklomfmflvcw.supabase.co/functions/v1/b2b-api"
export FLOVVY_KEY="flv_test_…"

# 1. Is the service up?
curl "$FLOVVY_BASE_URL/v1/status"

# 2. Send a photo and wait up to 30 seconds for the result
curl -X POST "$FLOVVY_BASE_URL/v1/receipts" \
  -H "Authorization: Bearer $FLOVVY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d "{\"image_base64\": \"$(base64 -w0 receipt.jpg)\", \"client_reference\": \"order-1042\", \"wait\": 30}"

(On macOS use base64 -i receipt.jpg instead of base64 -w0 receipt.jpg.) With a test key the answer comes at once and is always the same example (section 7).

No code yet? On the try page you paste your key, choose a photo of a receipt and see the JSON the API returns. Switch to the live key when

your integration works: nothing else changes.

Call the API from your server only. Never put a key in a browser page or a mobile app: anyone could read it. (Calls from a browser are accepted only from flovvy.app, for the try page.)

2. Authentication

Every call except /v1/status needs your key in the Authorization header:

Authorization: Bearer flv_live_…

• Test keys (flv_test_) never read real images and never use credits. Test and live are separate worlds: a test key cannot read receipts created with a live key, and the other way round.
• Keep keys secret. If a key leaks, or you want to rotate it, ask us: we give you a new one and keep the old one working for up to 72 hours, so you can switch without downtime.
• A missing, malformed, unknown or revoked key gets 401 unauthorized.

3. Credits

Live receipts are prepaid with credits: 1 credit = 1 receipt. You buy credits from us; we load them on your account.

• The credit is reserved when the receipt is accepted. If you have 5 credits and send 100 photos at once, 5 are accepted and 95 get 402 insufficient_credits immediately (nothing is stored for them).
• You pay for every reading we actually perform. A completed receipt uses its credit (also with reconciled: false), and so does a failed one whose photo we did read: unreadable (not a receipt, too blurry) or total_not_found.
• The credit comes back automatically when the failure is on our side and the reading was not performed or not delivered in time: provider_unavailable, timeout, and processing_error before the reading. Every failed receipt tells you which case it is: failure.credit_refunded (section 7).
• Free: test keys, and repeats of a request with the same Idempotency-Key (same receipt, section 6).
• Every response that creates a live receipt carries Flovvy-Credits-Remaining: your balance right after this receipt reserved its credit. A 402 carries it too.
• Read your balance at any time with GET /v1/balance (section 8).
• Packs (one-off top-ups) never expire. With a monthly plan, the month's credits are used first and the unused ones expire at renewal, when the new month's credits arrive; if the plan ends, at the end of the last paid month. A credit that comes back returns to the part it came from (to your other credits if the plan has expired meanwhile).

4. Send a receipt — POST /v1/receipts

Body (JSON):

Optional header: Idempotency-Key (section 6).

The photo. One receipt per photo, the whole receipt in the frame. We recommend what our own app does: longest side 2,000 px, JPEG quality 85.

The answer.

• 202 Accepted — the receipt is queued or processing. The Location header says where to read it (relative to the base URL), for example /v1/receipts/rcp_966dfd59aa2148328aad3878a08cb4fd.
• 200 OK — only when you used wait and the receipt finished in time: it is already completed or failed.

Example — 202 from a live key, without wait:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/receipts/rcp_966dfd59aa2148328aad3878a08cb4fd
Flovvy-Credits-Remaining: 99
Flovvy-Request-Id: req_1701e4119387d59592682c19

{
  "id": "rcp_966dfd59aa2148328aad3878a08cb4fd",
  "object": "receipt",
  "status": "queued",
  "environment": "live",
  "client_reference": "order-1043",
  "created_at": "2026-10-15T14:06:22.231Z",
  "completed_at": null,
  "schema_version": "2026-10-15",
  "pipeline_version": null,
  "merchant": null,
  "category": null,
  "issued_on": null,
  "currency": null,
  "totals": null,
  "lines": [],
  "reconciled": null,
  "reconciliation": null,
  "failure": null,
  "warnings": []
}

The receipt always has all its fields: when something is not known (yet), the value is null (or [] for lines).

5. Get the result

Two ways, use whichever suits you:

1. Wait in the same call — send "wait": 30. A receipt is usually read in a few seconds (4-7 s in our measurements), so you usually get 200 with the result. If not ready in time you get 202 and continue with option 2.
2. Poll — GET /v1/receipts/{id} every 1-2 seconds until status is completed or failed.

Status lifecycle:

queued ──► processing ──► completed
   ▲            │
   └────────────┤  (our AI provider busy: automatic retry after 1, then 4 minutes)
                └──► failed

If our AI provider is temporarily unavailable, the receipt goes back to queued and is retried automatically (up to 3 attempts in total): in that case the result can take a few minutes. You do not need to resend it.

Send in parallel. You don't need to wait for one receipt before sending the next: receipts are read in parallel. In three load tests in October 2026, 106 receipts sent at once were all read in 6.8 to 8.3 seconds, measured from when they reached us. When several customers are sending at the same time, each gets an equal share of the capacity, and a customer alone gets all of it.

GET /v1/receipts/{id} returns 404 not_found for an id that does not exist or belongs to someone else (or to the other environment): we never confirm that someone else's receipt exists. Receipts are kept for 90 days (section 14).

6. Idempotency — safe retries

Network errors happen. To retry without paying twice or getting two receipts, send an Idempotency-Key header with any value you choose — your own document id is ideal.

• 1-255 printable ASCII characters, no spaces at the start or end.
• Valid for 24 hours, separately for each account and environment (your key never collides with another customer's).
• Same key + same request (same image, mime and client_reference) → the same receipt, with header Idempotent-Replayed: true. No new reading, no new credit. wait does not count: you can retry with a different wait.
• Same key + different request → 409 idempotency_conflict.

7. The receipt object

A real example (test key, the fixed example):

{
  "id": "rcp_66f9b6e6f336492cb548530936316513",
  "object": "receipt",
  "status": "completed",
  "environment": "test",
  "client_reference": "order-1042",
  "created_at": "2026-10-15T14:06:22.179Z",
  "completed_at": "2026-10-15T14:06:22.179Z",
  "schema_version": "2026-10-15",
  "pipeline_version": null,
  "merchant": { "name": "EXAMPLE MARKET", "country": "IT" },
  "category": "groceries",
  "issued_on": "2026-10-14",
  "currency": "EUR",
  "totals": { "total": 3.98, "total_source": "printed", "tax": 0.36, "discounts": null, "net_of_tax": 3.62 },
  "lines": [
    { "n": 1, "kind": "item", "description": "BANANAS ORGANIC", "quantity": 1, "unit_price": 2.58, "total": 2.58,
      "weight": 1.29, "unit": "kg", "price_per_unit": 2, "applies_to": null },
    { "n": 2, "kind": "item", "description": "STILL WATER 1.5L", "quantity": 6, "unit_price": 0.35, "total": 2.1,
      "weight": null, "unit": null, "price_per_unit": null, "applies_to": null },
    { "n": 3, "kind": "discount", "description": null, "quantity": null, "unit_price": null, "total": -0.7,
      "weight": null, "unit": null, "price_per_unit": null, "applies_to": 2 }
  ],
  "reconciled": true,
  "reconciliation": { "status": "reconciled", "delta": 0, "tolerance": 0, "basis": "lines" },
  "failure": null,
  "warnings": ["test_mode"]
}

Top level

Categories: groceries, food_and_drink, vehicle, home, utilities, health, shopping, entertainment, sport, education, travel, technology, subscriptions, gifts, beauty, tobacco, other.

totals

lines

In printed order. Amounts are numbers in the receipt's currency.

reconciled and reconciliation — do the numbers add up?

reconciled: true means: the lines, together with the printed tax and discounts, add up exactly to the printed total (to the cent; to the unit for currencies without decimals, such as JPY). It is a strong sign that no line is missing or misread — but it does not prove every single line is right. false means they do not add up: check that receipt. null means it cannot be checked (no printed total, or no itemised lines).

failure — when status is failed

credit_refunded says whether the credit of this receipt came back to your balance. The rule: a reading we performed is paid, a reading we could not perform or deliver in time is not.

warnings

8. Your balance — GET /v1/balance

{ "object": "balance", "credits": 5099, "plan_credits": 5000, "plan_credits_expire_at": "2026-11-19T10:00:00.000Z",
  "updated_at": "2026-10-19T14:06:22.231Z" }

Test keys can read the balance too.

9. Risk checks — POST /v1/receipts/{id}/checks

On request, we check a receipt you already sent: duplicates among your receipts, a payment that does not match, an edited or AI-generated image, totals that do not add up. The answer is a list of signals with a risk level (none, low, medium, high): what a person should look at, never a verdict. No credits, no AI, nothing changes.

This call has its own base URL: https://phxkxiktoklomfmflvcw.supabase.co/functions/v1/b2b-antifrode.

curl -X POST "https://phxkxiktoklomfmflvcw.supabase.co/functions/v1/b2b-antifrode/v1/receipts/rcp_966dfd59aa2148328aad3878a08cb4fd/checks" \
  -H "Authorization: Bearer $FLOVVY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expected": { "amount": 12.50, "currency": "EUR", "date": "2026-10-19", "merchant": "UBER *TRIP" } }'

The body is optional: without expected every check runs except the payment match. The full guide — every signal, how each check works, the response — is in Risk checks.

10. Errors

Errors follow RFC 9457 (Content-Type: application/problem+json). Use code in your code: it never changes. detail is for humans and may be reworded.

{
  "type": "https://api.flovvy.app/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "Not enough credits: your balance is 0. Each receipt uses 1 credit; top up to continue.",
  "request_id": "req_f8751e21e1195cf96c60b00e"
}

11. Response headers

12. Versions and compatibility

• The path carries the API version (/v1/); the receipt carries schema_version.
• We may add new fields (and new warnings or category codes) at any time without changing the version: ignore fields you do not know, and treat unknown codes as other.
• Renaming or removing a field, or changing its meaning, means a new schema_version, announced in advance.
• Results improve over time: pipeline_version tells you which version of our engine read a receipt.

13. Code examples

JavaScript (Node 18+)

import { readFile } from 'node:fs/promises';

const BASE = process.env.FLOVVY_BASE_URL;
const KEY = process.env.FLOVVY_KEY;

async function readReceipt(file, reference) {
  const image_base64 = (await readFile(file)).toString('base64');
  const headers = { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': reference };
  let res = await fetch(`${BASE}/v1/receipts`, {
    method: 'POST', headers, body: JSON.stringify({ image_base64, client_reference: reference, wait: 30 }),
  });
  if (res.status === 402) throw new Error('No credits left');
  if (!res.ok) throw new Error(`${res.status} ${(await res.json()).code} — request ${res.headers.get('flovvy-request-id')}`);
  let receipt = await res.json();
  while (receipt.status === 'queued' || receipt.status === 'processing') {     // not ready within 30 s: poll
    await new Promise((r) => setTimeout(r, 2000));
    res = await fetch(`${BASE}/v1/receipts/${receipt.id}`, { headers: { Authorization: `Bearer ${KEY}` } });
    receipt = await res.json();
  }
  return receipt;   // status: 'completed' or 'failed'
}

const r = await readReceipt('receipt.jpg', 'order-1042');
console.log(r.status, r.merchant?.name, r.totals?.total, r.currency, `${r.lines.length} lines`, 'reconciled:', r.reconciled);

Python (requests)

import base64, os, time, requests

BASE = os.environ["FLOVVY_BASE_URL"]
KEY = os.environ["FLOVVY_KEY"]
AUTH = {"Authorization": f"Bearer {KEY}"}

def read_receipt(path, reference):
    with open(path, "rb") as f:
        image_base64 = base64.b64encode(f.read()).decode()
    res = requests.post(f"{BASE}/v1/receipts",
                        headers={**AUTH, "Idempotency-Key": reference},
                        json={"image_base64": image_base64, "client_reference": reference, "wait": 30},
                        timeout=40)
    if res.status_code == 402:
        raise RuntimeError("No credits left")
    res.raise_for_status()
    receipt = res.json()
    while receipt["status"] in ("queued", "processing"):   # not ready within 30 s: poll
        time.sleep(2)
        receipt = requests.get(f"{BASE}/v1/receipts/{receipt['id']}", headers=AUTH, timeout=10).json()
    return receipt   # status: "completed" or "failed"

r = read_receipt("receipt.jpg", "order-1042")
print(r["status"], (r["merchant"] or {}).get("name"), (r["totals"] or {}).get("total"), r["currency"], r["reconciled"])
for line in r["lines"]:
    print(line["n"], line["kind"], line["description"], line["quantity"], line["weight"], line["unit"], line["total"])

curl — read a receipt and the balance

curl "$FLOVVY_BASE_URL/v1/receipts/rcp_966dfd59aa2148328aad3878a08cb4fd" -H "Authorization: Bearer $FLOVVY_KEY"
curl "$FLOVVY_BASE_URL/v1/balance" -H "Authorization: Bearer $FLOVVY_KEY"

14. Data retention

• Photos are deleted 7 days after the receipt was sent.
• Receipts (with their result) are deleted 90 days after they were sent. After that, GET /v1/receipts/{id} returns 404 not_found: store the results you need on your side.
• Your credit history is kept (it is what you are billed on), without the receipt content.
• Receipts we misread — failed, or reconciled: false — may be kept up to 12 months to improve the reading of your receipts and the service, unless you opt out (in the console, Team & account → Documents, or by writing to us; data processing agreement, article 13). Receipts in the health category never are. They are never shown to other customers or used to train anyone else's AI.

15. Support

Write to us with the Flovvy-Request-Id of the call and, if there is one, the receipt id. With those two we can find exactly what happened. Never send us your API key.