DEV Community

Daniel Pertu
Daniel Pertu

Posted on

Our free tier is five scans a month, and the only thing counting them is the phone

Open munchable.app and look at the phone mock near the top of the page. Under the barcode it says:

5 of 5 free scans left this month

That line is real product copy, not marketing filler. The free plan allows five scans a calendar month and Premium is unlimited, which the pricing section states in one sentence. What I want to write about is where that number lives, because the obvious answer is wrong.

It is not in our database. Nothing on our servers knows you have scanned anything at all.

The counter is two values in device storage

The whole quota is a string and an integer in the on-device profile, persisted to AsyncStorage:

/** Free tier: scans per calendar month (premium = unlimited). */
export const FREE_SCAN_LIMIT = 5;

// ...
scanPeriod: string;        // "2026-11"
scansThisPeriod: number;   // 0..n
Enter fullscreen mode Exit fullscreen mode

Reading what is left is three lines:

remainingScans: () => {
  if (get().isPremium) return Infinity;
  const used = get().scanPeriod === currentPeriod() ? get().scansThisPeriod : 0;
  return Math.max(0, FREE_SCAN_LIMIT - used);
},
Enter fullscreen mode Exit fullscreen mode

The period being a plain year-month string is the part I like most. There is no monthly reset job, no scheduled task, no row to update at midnight on the first. A period that is not the current period reads as zero used. The month rolls over because the comparison stops matching, and the stale integer is overwritten the next time a scan is counted. A feature that would have been a cron job in a server-side design is an equality check here.

What the server does own

The server owns exactly one thing about your plan, and it answers in four fields:

GET /api/entitlement -> { isPremium, plan, status, renewsAt }
Enter fullscreen mode Exit fullscreen mode

It reads the caller's own row from one table, maps the billing statuses that still grant Premium onto a boolean, and returns. No row means free. The handler's comment is blunt about its scope: billing state only, never any condition or health data.

The client treats that as the truth and keeps nothing of its own:

} catch {
  // Never grant Premium on error; keep prior state, drop the spinner.
  set({ loading: false });
}
Enter fullscreen mode Exit fullscreen mode

So the split is: the server decides whether you are Premium, and the device decides how many free scans you have left. There is no table in the schema with a scan count in it. I went looking to be sure before writing this, and the only thing resembling a scan counter anywhere in the database describes products, not people.

Why we did not put the counter on the server

Putting it there is easy. One row per account per month, increment on lookup, and suddenly the limit survives a reinstall. We decided against it, and the reason is on the page we have to stand behind: our privacy notice says the conditions you manage and the scans you make stay on your device.

A per-account monthly scan counter would be the one table in the product that records your shopping behaviour. Not what you scanned, but how often and when, tied to your email. Five rows a month is enough to tell when somebody does their weekly shop, when they stopped using the app, and when they started again. For a product whose entire proposition is that the health part never leaves the handset, that table is the wrong trade for an enforcement property we do not actually need.

Which brings up the obvious objection.

Yes, a reinstall resets it

It does. Clear the app's storage and you get five more scans.

That is a known cost, not an oversight, and the reason it is survivable is that the gate is a nudge rather than a licence check. The paywall it opens is the same screen whether you have one scan left or none:

const line = outOfScans
  ? `You've used all ${FREE_SCAN_LIMIT} free scans this month. Go unlimited with Premium.`
  : `You're on the free plan with ${remaining} of ${FREE_SCAN_LIMIT} scans left this month. Go unlimited with Premium.`;
Enter fullscreen mode Exit fullscreen mode

Compare it with the things we do defend properly. Premium itself is server-side and fails closed. An account is required before anything scans at all, and the gate is written so a misbuilt production app with missing backend keys refuses rather than silently opening up. Those are the properties worth spending a database on. A free-tier count is worth two values in local storage.

Reading the quota three times in one scan

The counter is read in more places than you would expect for a single number, and each read does a different job.

Before the lookup, it decides whether a scan happens:

// Gate on quota before scanning, but only count the scan once a product
// is actually found and a verdict shown. A not found scan costs nothing.
if (useProfile.getState().remainingScans() <= 0) {
  setWaitAt(0);
  router.push('/paywall');
  return;
}
Enter fullscreen mode Exit fullscreen mode

Earlier than that, the camera speculatively prefetches a barcode it has only half-confirmed, and the quota decides whether to bother. The comment explains why that read cannot be the gate:

// Reading quota here also cannot GRANT anything: the gate that decides
// is the one in `handle`, which runs after this and reads the store
// again.
Enter fullscreen mode Exit fullscreen mode

The second half of that comment is the one I would keep if I could only keep one line: a prefetch for somebody with no quota left is a barcode off the user's camera that we had no reason to see. The quota read is doing privacy work there, not accounting work.

And then the count itself happens after a product is found and shown, never on the attempt. A scan that comes back with nothing in the catalogue sends you to the label camera instead, and it is free. There is also a guard so that one barcode cannot be charged twice when the scanner re-arms mid-lookup, because two scans of the same code either side of a re-arm get handed the same answer, and only one of them may count.

The shape of the lesson

The free limit is the kind of feature that invites a schema change by reflex. Ours ended up as:

  • one exported constant
  • two persisted values
  • one equality check standing in for a monthly reset
  • zero server state
  • one accepted loophole, written down

If you want to see the behaviour, the homepage mock shows the exact string the app shows, and the pricing section states the limit. The conditions the app actually weighs a product against, which are the thing that never leaves the device, each have a page of their own under munchable.app/conditions.

Top comments (0)