Sume reserve, capture, refund: what your cost ledger should mirror

Sume bills a paid generation in three steps: reserve the estimate when the request is accepted, capture the usage when the job completes, and release or refund the reservation when it fails or is canceled before capture. Your own cost records should follow the same states, or a queued job will look like spend that never happens.

The three states

The docs describe usage as public USD estimates reserved at submit. A submit that cannot reserve the estimate fails 402 insufficient_credits before provider work starts, and a failed queue admission also releases its reservation. GET /v1/usage lists these ledger entries, such as reservations, captures, refunds and top-ups, and GET /v1/balance returns available balance.

Pitfalls

Do not add reservations to captures, since a completed job shows both. Do not read available balance as final spend while jobs are queued; held amounts are not available but are not spent yet. When a client timeout fires, the job keeps running and will capture, so keep the id.

A weekly check

Once a week, sum captures from the usage ledger and compare with your per-job records. Differences usually mean a job id you never stored.