Sume reserve, capture, refund: what your cost ledger should mirror
Sume reserves the estimate at submit, captures it on success and releases it on failure or cancel. Mirror the three states or cost reports will double count.
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.
| Event | Ledger effect | Your record |
|---|---|---|
| Submit accepted | Reservation of the estimate | Held |
| Job completed | Capture of actual usage | Spent |
| Job failed or canceled before capture | Reservation released or refunded | Released |
| Submit refused 402 | Nothing reserved | Not started |
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.
Sources
Related posts
More in Developers
- Sume schedule run statuses: completed, failed, canceled, skipped
Sume schedule runs report completed, failed, canceled with one l, and skipped. They are a remap of internal statuses, so job-side strings do not carry over.
- Paging Sume schedule runs: limit 1-100, next_cursor, has_more
List a Sume schedule's runs with limit 1-100 (default 50), then pass next_cursor back as cursor until has_more is false. A forged cursor is a 400. Python loop.
- Sume schedule vanity URL: store the aut_ id, not handle/slug
A Sume schedule can be run at /v1/actions/{handle}/{slug}/runs, but renaming either part changes the path. Store the aut_ id; an old handle resolves 90 days.
- Sume SDK 429 retry-after is capped at 60 seconds: what follows
createSumeClient waits at most 60 seconds per retry, with 20 percent jitter and 2 retries by default. What that means for a long retry-after and a fix.
Written by Sume