Skip to content

Caching results

Every result carries valid_until: the earliest future instant when the answer can change without anyone writing anything. Until then, only a write (a new plan version assigned, an override created, a subscription edited) can change it.

It’s the earliest of:

  • the end of an active override, or the start of a future one, for this feature;
  • the subscription’s period end, trial end, grace end or cancellation time;
  • for metered features, the end of the usage period, when usage resets.

null means no such instant is known.

Cache each answer per Customer and feature, and expire it at whichever comes first: valid_until, or a short time you choose.

const ttlMs = 60_000; // your bound on how stale a write may be
const expires = Math.min(Date.now() + ttlMs, entitlement.valid_until ? Date.parse(entitlement.valid_until) : Infinity);
  • The short bound covers writes, which valid_until can’t predict.
  • valid_until covers time passing: a trial ending at midnight is never served from cache after midnight.
  • evaluate-all gives every feature at once, so one request fills the cache for a page load.

If your billing code assigns subscriptions or creates overrides, drop that Customer’s cached answers right after the write succeeds. Then the short bound only matters for changes made in the Console.

Usage changes with every recorded unit, so cache metered answers briefly, or not at all, near the limit. usage.remaining tells you how close a Customer is.

A cached answer that’s still within its valid_until is a safe fallback. Past that, fail closed: treat the feature as not granted.