The situation
Keto Kartel sells healthy meal kits and supplements on weekly and monthly subscription cycles. The subscription model creates a layer of operational complexity that a standard e-commerce build isn't designed to handle: every customer's subscription can be in a different state at any moment — active, paused, mid-cycle-downgrade, product-swapped — and billing runs on a schedule regardless of what state changes happened in the preceding period. The original flat subscription schema treated all of this as simple on/off flags. When a customer upgraded mid-cycle, the system didn't know how to prorate correctly. When billing ran, it read current state rather than the state at billing time — meaning a customer who paused after the billing cutoff still got charged. Inventory deductions happened at order creation rather than at actual billing, creating phantom reservations that led to stockouts on popular products. We redesigned the subscription system from the schema up. Subscription state is now tracked as explicit transitions with timestamps — the billing engine always reads what the state *was* at the billing moment, not what it is now. Billing uses idempotency keys: each billing cycle has a unique key that prevents any charge from being executed twice regardless of network failures or retries. Inventory deduction is a separate queue job that only fires on successful billing confirmation.
What had to change
Double charges from billing retry races. Incorrect prorations when customers changed plans mid-cycle. Inventory phantom reservations from failed-then-retried billing attempts. Customer service was handling dozens of billing complaints monthly — a direct cost in refunds and staff time that was eating into margins.
What we changed
Schema redesign with explicit state transitions and timestamps. Idempotency keys on every billing operation — the same key submitted twice produces one charge, always. Inventory deduction as a confirmed-billing-event subscriber, never at order creation. Proration logic based on time-weighted state history, not current state at billing time. Zero double charges since deployment.
What the client gained
- 01 Idempotent billing — physically impossible to double-charge
- 02 State-transition schema — accurate proration always
- 03 Inventory only decrements on confirmed billing event
- 04 6 subscription tiers with full plan-change flexibility
