A Gift Card Balance Is a Projection, Not Just a Number

The first version of a gift card balance often looks like one database column: balance = 70. It works until someone asks a reasonable question: why is it 70?

Was a purchase completed? Is part of the value temporarily held? Did a failed checkout release its hold? A single number cannot answer those questions on its own.

I find it more useful to think of the balance shown to a customer as a projection of events. The events explain how the card got there; the number is only the current view.

A small example

Imagine a card issued with $100 of value:

The reservation changes what can be spent right now, but it does not mean $20 has been redeemed. That distinction matters when a checkout times out or a payment is abandoned.

If the checkout succeeds instead, the $20 hold becomes a capture: reserved value falls to zero and unspent value falls to $50. The available amount stays at $50 because it was reduced when the hold was created.

Make each transition explicit

One possible event model is:

type Event = | { kind: "issued"; amount: number } | { kind: "redeemed"; amount: number } | { kind: "hold_created"; amount: number } | { kind: "hold_released"; amount: number } | { kind: "hold_captured"; amount: number }; function project(events: Event[]) { let available = 0; let reserved = 0; for (const event of events) { switch (event.kind) { case "issued": available += event.amount; break; case "redeemed": available -= event.amount; break; case "hold_created": available -= event.amount; reserved += event.amount; break; case "hold_released": reserved -= event.amount; available += event.amount; break; case "hold_captured": reserved -= event.amount; break; } } if (available < 0 || reserved < 0) throw new Error("Invalid ledger state"); return { available, reserved, unspent: available + reserved }; } 

This reducer is a way to read the history, not a complete transaction system. In production, the write that creates a hold has to be atomic with the check that enough value is available. Each hold also needs an identifier, so a release or capture applies to the right checkout rather than merely subtracting an amount from a shared bucket.

The question I'd put on the dashboard

Instead of showing only “Balance: $50,” I would show “$50 available” and, when relevant, “$20 pending.” The support view should show the event trail behind both figures. If a customer says a purchase failed but their balance dropped, there is now a concrete place to look.

This is the kind of small systems detail I pay attention to when writing about gift cards at CardNaro. The interesting question is rarely just what is the balance? It is what happened to it?