ikieEngineeringGet started
All posts

Data modelBillingDesign

We don't store your plan, we compute it

ikie has no column that says "this person pays". We record only facts, App Store subscriptions and grants, and compute the plan and any pauses on every request, so nothing is deleted or changed when a plan ends and nothing needs undoing when someone subscribes again.

한국어

ikie has a paid plan, Hyper ikie. It covers things like connecting several external calendar accounts, setting edit rules, finding free time across other people's calendars, calling ikie from connected tools (MCP), and making flagged tasks shimmer. We're launching free, so the paywall is off for now, but the structure is built.

The easiest way to add billing is a plan = 'plus' column on the users table. We didn't add one.

Record facts, not the plan

What ikie records is an entitlement, a fact. One row says "this person has this product until this time".

ColumnMeaning
sourceWhere it came from: an App Store subscription, or a direct grant
product_idWhich product
original_transaction_idThe App Store subscription's identity. One subscription belongs to one person
expires_atWhen the paid period ends
grace_untilWhen the App Store billing grace period ends
revoked_atWhen it was taken back, for example after a refund

The plan is computed from these rows.

export const entitlementEnd = (e) => (e.expiresAt === null ? null : Math.max(e.expiresAt, e.graceUntil ?? e.expiresAt));
export const entitlementLive = (e, now) => { const end = entitlementEnd(e); return e.revokedAt === null && (end === null || end > now); };
export function activeEntitlement(rows, now) {
  const on = rows.filter((e) => entitlementLive(e, now) && planOfProduct(e) === "plus");
  return on.sort((a, b) => (entitlementEnd(b) ?? Infinity) - (entitlementEnd(a) ?? Infinity))[0] ?? null;
}
export const planOf = (rows, now) => (activeEntitlement(rows, now) ? "plus" : "free");

Cancel, and you keep Hyper until the paid period ends. During the grace period while the App Store retries billing, you're still Hyper. After a refund, you're free from the moment it was revoked. All of it comes down to one question: is there a live entitlement right now? It's a pure function that takes the current time as an argument, so it's tested without a database.

What if we'd stored a plan column? Someone would have to flip it the moment it expires. If the cron job or the App Store notification runs late, the value is wrong in between. Grants from the admin screen and refunds would each need the column kept in step. Compute it, and there's no such moment. The admin screen's "grant Hyper" and "revoke" simply add or revoke an entitlement row.

What each feature counts, in one place

The candidate paid features and their free limits live in one file.

FeatureFreeCounted as
Calendar accounts1A count. iPhone calendars and .ics subscriptions don't count
Edit rulesHyper onlyOn or off
Connected toolsHyper onlyOn or off
Free timeFree for me and my own calendarsOn or off
ShimmerHyper onlyOn or off

Whether the paywall is on, each feature's limit, and which products are for sale are server settings. They're changed in the admin screen, and the calculation receives them as validated rules.

Server code that uses a feature (a use case) passes through a plan gate first. With the paywall off, the gate opens without even reading entitlements. When blocked, it returns 402 plus_required along with which feature and which limit. The web catches this from every API response and shows the Hyper prompt from one place. A connected Claude gets the same plus_required as a tool result. Screens never re-decide whether someone pays.

Nothing is deleted when it ends

The harder question was what happens when a plan ends. If someone with three connected calendar accounts drops to free, what happens to the other two? Disconnect them, and subscribing again means connecting from scratch, with events tangled in between. Change their settings, and the app has quietly edited something the user set up.

We set the rule in one line: leave the data as the user set it, have reads and writes check the current plan through the same function, and when Hyper returns, everything simply continues. Each feature declares one of three ways to end.

  • Hold what's over (holdOver). Calendar accounts over the free limit stop both fetching and sending, and stay on the board read-only, exactly as last seen. The user picks which to keep with "keep this account".
  • Keep what exists (keepExisting). Edit rules already set keep working. Only setting new ones or changing them is blocked. Removing always works.
  • Block on use (blockUse). Connected tools, free time and the shimmer go through the gate on every use, so they stop working from the moment the plan ends.

Here too, "paused" isn't stored. It's computed on each request from the account owner's plan and their list of accounts. Accounts to keep come first by the most recent "keep" choice (kept_at), then by which was connected earliest.

export const PLAN_LAPSE = { calendarAccounts: "holdOver", editPolicies: "keepExisting", connectedTools: "blockUse", freeTime: "blockUse", glow: "blockUse" };

Because pausing isn't stored, there's nothing to undo the moment someone subscribes again. From the next request the calculation answers "nothing is paused", and syncing continues from the last agreed base.

Three paths, one judgment

Reading, writing and syncing external calendars must all treat a paused account the same way. Reads show it as read-only, so writes must not accept changes to it, and syncing must not quietly send anything either. So all three look at one place. For each request, the paused accounts are computed once per owner, and that fact feeds the edit decision (canEdit). For a calendar shared with you, it's the account owner's plan that counts, not yours. The sync engine knows nothing about plans. It only receives the list of paused accounts.

Tests hold this principle too. They check that a second account inserted straight into the database, bypassing the connect flow, is still paused when the owner goes free, that everything continues when Hyper returns, and that edit rules set earlier survive the lapse.

The shimmer is computed too

A flagged task's shimmer isn't stored either. When the server reads the board, it decides from "is it flagged × is the shimmer setting on × does the plan allow it". Screens draw what they receive. When the plan ends, the shimmer stops but the flag stays. The flag is a fact the user set, and the shimmer is computed on top of it.

The App Store behind an adapter

App Store transactions and server notifications have their signatures verified with Apple's official library and Apple's root certificate. That check is an adapter behind a port, so use cases receive only verified transactions. We refuse an unknown product, a transaction naming a different account, or a subscription already attached to someone else. The iOS app hands the transaction to the server and finishes it only after the server has decided whether to accept it. If the server can't be reached, the transaction stays unfinished and the app hands it over again the next time it opens.

What we learned

A plan is a value that changes on its own as time passes. Store a value like that, and someday someone has to change it on time, and "on time" always turns into a bug. Record only the facts (entitlements) and compute from the current time, and cancelling, grace periods, refunds and grants all resolve through one function. Ending a plan worked the same way. We pause by calculation instead of deleting or changing anything, so there's nothing to undo for someone who comes back.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.