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".
| Column | Meaning |
|---|---|
| source | Where it came from: an App Store subscription, or a direct grant |
| product_id | Which product |
| original_transaction_id | The App Store subscription's identity. One subscription belongs to one person |
| expires_at | When the paid period ends |
| grace_until | When the App Store billing grace period ends |
| revoked_at | When 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.
| Feature | Free | Counted as |
|---|---|---|
| Calendar accounts | 1 | A count. iPhone calendars and .ics subscriptions don't count |
| Edit rules | Hyper only | On or off |
| Connected tools | Hyper only | On or off |
| Free time | Free for me and my own calendars | On or off |
| Shimmer | Hyper only | On 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.