Cart reservation timer API

Begin checkout

// The customer commits: reserve stock and start the clock.
export async function beginCheckout(order) {
  await db.reserveStock(order.items);

  const timer = await call("/timers", {
    method: "POST",
    // Derived from the order, so a retried request returns the
    // original hold rather than granting another fifteen minutes.
    headers: { "Idempotency-Key": `hold_${order.id}` },
    body: JSON.stringify({
      name: `Cart hold ${order.id}`,
      type: "duration",
      duration_seconds: 15 * 60,
      metadata: { order_id: order.id },
      publish: true,
      expiry: { behavior: "show_message", message: "This reservation has expired" },
    }),
  });

  await db.orders.update(order.id, { timerId: timer.id });

  // One rule: tell us at zero.
  await call(`/timers/${timer.id}/webhook-rules`, {
    method: "POST",
    body: JSON.stringify({
      name: "Hold expired",
      webhook_destination_id: DESTINATION_ID,
      condition: { field: "status", operator: "equals", value: "ended" },
    }),
  });

  // Nothing counts down until it is started.
  await call(`/timers/${timer.id}/actions`, {
    method: "POST",
    body: JSON.stringify({ action: "start" }),
  });

  return timer;
}

Charge with the clock frozen

// Payment authorisation can take thirty seconds. That time
// should not come out of the customer's fifteen minutes.
export async function chargeOrder(order) {
  await action(order.timerId, "pause");

  try {
    const result = await paymentProvider.charge(order);

    if (result.requiresAction) {
      // 3-D Secure. Hand the remaining time back untouched.
      await action(order.timerId, "resume");
      return result;
    }

    if (result.succeeded) {
      // Done. The hold is no longer needed.
      await call(`/timers/${order.timerId}`, { method: "DELETE" });
      return result;
    }

    // Declined. Give the full window back for another card.
    await action(order.timerId, "reset");
    await action(order.timerId, "start");
    return result;
  } catch (error) {
    // Never leave a hold frozen forever because we threw.
    await action(order.timerId, "resume").catch(() => {});
    throw error;
  }
}

Webhook handler and release job

// The webhook handler. Fires at zero, without polling.
app.post("/webhooks/countdownshare", raw, async (req, res) => {
  if (!verify(req.body, req.headers, SECRET)) return res.sendStatus(401);

  res.sendStatus(200);   // acknowledge inside 10 seconds

  const event = JSON.parse(req.body.toString());
  if (event.data.status !== "ended") return;

  await queue.add(
    "release-hold",
    { orderId: event.timer.metadata.order_id },
    // At-least-once delivery: the same event can arrive twice.
    { jobId: event.id },
  );
});

// The job itself must be safe to run more than once.
async function releaseHold({ orderId }) {
  const order = await db.orders.find(orderId);

  // Idempotent by construction: already-released is a no-op,
  // and a paid order is never touched.
  if (!order || order.status !== "awaiting_payment") return;

  await db.transaction(async (tx) => {
    await tx.orders.update(orderId, { status: "expired" });
    await tx.releaseStock(order.items);
  });
}

Confirm before processing

// The countdown on screen is presentation. The decision is not.
export async function confirmOrder(order) {
  const status = await call(`/timers/${order.timerId}/status`);

  if (status.ended) {
    throw new HoldExpiredError("This reservation has expired");
  }

  return processOrder(order);
}