Personalized countdown timers

How it differs from the others

A fixed countdown ends at the same instant for everyone. A duration timer counts elapsed time but has to be started and can be paused. A personalized timer starts itself, at creation, per identity — and cannot be paused, because the whole point is that the deadline is settled.

Creating one

Both duration_seconds and external_user_id are required. The identifier is 1–255 characters and entirely yours — the API stores it and returns it, and does not interpret it.

curl -X POST https://countdownshare.com/api/v1/timers \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trial_customer_8f21c" \
  -d '{
    "name": "Trial ends",
    "type": "personalized",
    "duration_seconds": 1209600,
    "external_user_id": "customer_8f21c",
    "publish": true,
    "expiry": {
      "behavior": "redirect",
      "redirect_url": "https://example.com/upgrade"
    }
  }'

Choosing the identifier

It has to be stable. If it changes, you lose the link between the person and their countdown — and the API cannot help you find it again.

Wiring it into signup

Create the timer at the moment the window should start, and make the create idempotent against the customer. This is the single most important detail in the integration: without a stable key, a retried signup request creates a second timer and quietly hands someone a twenty-eight day trial.

// On signup: one timer, created once, for this customer.
//
// The idempotency key is derived from the customer, so a retry
// after a timeout returns the original timer instead of giving
// them a second, longer trial.
export async function startTrial(customer) {
  const { data: timer } = await call("/timers", {
    method: "POST",
    headers: { "Idempotency-Key": `trial_${customer.id}` },
    body: JSON.stringify({
      name: `Trial — ${customer.email}`,
      type: "personalized",
      duration_seconds: 14 * 24 * 60 * 60,
      external_user_id: customer.id,
      publish: true,
      metadata: { plan: customer.plan, source: customer.source },
    }),
  });

  // Store the ID. It is how you find this customer's countdown later.
  await db.customers.update(customer.id, { countdownTimerId: timer.id });

  return timer;
}

See idempotency for why the key must be derived from the customer rather than generated at the call site.

The part that is genuinely hard elsewhere

A personalized deadline inside an email body, rendering the recipient's own remaining time, at the moment they open it. Not a static image baked at send time — a live animated GIF.

// The GIF URL goes straight into the email body. When the
// recipient opens it — today or in three days — the GIF is
// rendered then, showing THEIR remaining time.
const { data: outputs } = await call(`/timers/${timer.id}/outputs`);

await sendEmail({
  to: customer.email,
  subject: "Your trial ends soon",
  html: `
    <p>Hi ${customer.firstName},</p>
    <p>Your trial ends in:</p>
    ${outputs.email_embed_html}
    <p><a href="https://example.com/upgrade">Upgrade now</a></p>
  `,
});

The GIF is generated when the inbox requests it, which is why it is correct whether the email is opened immediately or three days later. It needs no JavaScript, which is what makes it work in Outlook, Gmail, and Apple Mail alike. Full detail under embeds and hosted pages.

Enforcing the deadline

The countdown is a display. The decision about whether someone still has access belongs on your server, checked at the moment it matters.

// Do not decide "expired" from the email or the page.
// Check it server-side at the moment it matters.
export async function canAccessTrialFeature(customer) {
  const { data } = await call(`/timers/${customer.countdownTimerId}/status`);
  return !data.ended;
}

Better still, do not poll at all — attach a webhook rule on status equals "ended" and downgrade the account when we call you. One request at signup, one callback at expiry, and nothing in between. Webhook rules.

Where this fits

Reassigning and extending

external_user_id is editable, so a timer can be moved to a different identity — useful when an account is merged. duration_seconds is editable too, which is how you extend a trial without creating a second timer and without it counting against your allowance again.

Both need the current revision in If-Match. Extending changes the window from the original start, not from now, which is usually what “give them another week” is meant to do — check that assumption against your own intent. See update and delete.