How a Utility SaaS Team Built Idempotent APIs Using Natural Domain Keys

A developer on a utility billing SaaS platform faced a reliability problem with a rate-plan comparison feature that re-ran full bill calculations per candidate plan, making it an expensive, slow REST call prone to client timeouts and retries. Without safeguards, retried requests could trigger duplicate computation runs and return inconsistent results to customers, undermining trust in a feature designed to guide rate-plan decisions. The standard fix — client-generated idempotency tokens mapped to cached results — works well when no natural request identity exists, such as with payment submissions. However, the team realized their comparison requests were fully identified by three existing domain fields: account, billing period, and the set of rate plans being compared. By enforcing database-level uniqueness on those natural keys, they achieved idempotency without requiring clients to generate or manage any tokens at all.