Countdown Timer API vs a cron job

The shape of each approach

The difference is not the language or the hosting. It is where the schedule lives: in a recurring sweep that inspects everything, or attached to the one record it concerns.

# Every minute, ask the database whether anything expired.
* * * * * /usr/local/bin/expire-holds

# expire-holds
SELECT id FROM cart_holds
WHERE expires_at <= NOW() AND released_at IS NULL
LIMIT 500;
-- …then release each one, and hope the job did not
-- overlap with the previous run still finishing.

// At the moment the hold is created:
await call("/timers", {
  method: "POST",
  headers: { "Idempotency-Key": `hold_${hold.id}` },
  body: JSON.stringify({
    name: `Cart hold ${hold.id}`,
    type: "duration",
    duration_seconds: 900,
    metadata: { hold_id: hold.id },
  }),
});

// …and once, anywhere in your app:
app.post("/webhooks/countdownshare", async (req, res) => {
  res.sendStatus(200);
  const event = JSON.parse(req.body);
  await releaseHold(event.timer.metadata.hold_id);
});

The cron version scales with the size of your table. The API version scales with the number of deadlines that actually exist, and does nothing at all in between.

Where they differ in practice

The three problems with polling for deadlines

Latency you cannot design away

A one-minute cron means an action happens somewhere between 0 and 60 seconds after it should. Shorten the interval and the query cost rises against a table that is mostly rows with nothing due. For a nightly report that lateness is irrelevant; for a checkout hold or an auction close it is the difference between correct and wrong.

Overlap, and the locking you now own

The moment a run takes longer than the interval, two runs are live at once and both will select the same rows.

# 00:00:00  run 1 starts, 4,000 rows to process
# 00:01:00  run 2 starts — run 1 is still going
# 00:01:04  run 2 selects rows run 1 has already claimed
#
# Two workers, same rows, two refunds issued.
#
# The fix is a lock, a claim column, or SKIP LOCKED —
# all of which you now own and have to test.

SELECT … FOR UPDATE SKIP LOCKED, an advisory lock, or a claim column all solve it. None is difficult. All of them are code you write, test, and maintain — and the bug only appears under the load where it hurts most.

Silence when it dies

A cron job that stops running produces no error. Nothing is logged, because nothing ran. Teams discover it when a customer asks why their reservation never expired, which is typically days later. Catching it early means a heartbeat and an alert — another small system to build.

What replaces the sweep

When cron is the right answer

Plenty of the time. The API is a poor fit for work that is genuinely periodic rather than deadline-shaped.

A good rule: if you would struggle to explain the deadline to a customer, it is probably batch work and cron is fine. If a customer could reasonably ask “how long do I have?”, the deadline belongs to a record and wants to be addressable.

Moving an existing cron sweep across

You do not have to switch everything at once. The usual path is to run both briefly and let the sweep become a safety net.

1. 01

   Create a timer alongside the record

   Wherever you currently set expires_at, also POST a timer with an Idempotency-Key derived from the record ID. Store the returned timer ID.

2. 02

   Add the webhook handler

   Point a rule at status equals "ended" and do the same work the cron job does — extracted into a function both can call.

3. 03

   Make the work idempotent

   Both paths may run for the same record during the overlap. "Set released_at if null" is safe; "add stock back" is not.

4. 04

   Widen the cron interval

   Once webhooks are handling the timely case, the sweep only needs to catch stragglers. Hourly is usually enough.

5. 05

   Keep it, or drop it

   A daily reconciliation sweep is cheap insurance. Plenty of teams keep one permanently and alert if it ever finds anything.

Common questions

Related