Trial expiry countdown API

startTrial

// One timer per customer, created at signup.
export async function startTrial(customer) {
  const timer = await call("/timers", {
    method: "POST",
    // Derived from the customer. A retried signup returns the
    // original timer instead of quietly granting 28 days.
    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,
      expiry: {
        behavior: "redirect",
        redirect_url: "https://example.com/upgrade",
      },
      metadata: { plan: customer.plan, source: customer.source },
    }),
  });

  await db.customers.update(customer.id, { trialTimerId: timer.id });
  return timer;
}

Attaching milestones

// Four rules, one timer, one destination. Rules are unlimited
// on every plan, so a reminder ladder costs nothing extra.
const MILESTONES = [
  { name: "7 days left", seconds: 7 * 86400 },
  { name: "3 days left", seconds: 3 * 86400 },
  { name: "1 day left", seconds: 86400 },
];

for (const milestone of MILESTONES) {
  await call(`/timers/${timer.id}/webhook-rules`, {
    method: "POST",
    body: JSON.stringify({
      name: milestone.name,
      webhook_destination_id: DESTINATION_ID,
      condition: {
        field: "remaining_seconds",
        operator: "less_than_or_equal",
        value: milestone.seconds,
      },
      delivery: "once",
    }),
  });
}

await call(`/timers/${timer.id}/webhook-rules`, {
  method: "POST",
  body: JSON.stringify({
    name: "Trial ended",
    webhook_destination_id: DESTINATION_ID,
    condition: { field: "status", operator: "equals", value: "ended" },
    delivery: "once",
  }),
});

One endpoint, branching on rule.name

// One endpoint, branching on the rule name you chose.
app.post("/webhooks/countdownshare", raw, async (req, res) => {
  if (!verify(req.body, req.headers, SECRET)) return res.sendStatus(401);
  res.sendStatus(200);

  const event = JSON.parse(req.body.toString());
  const customerId = event.timer.external_user_id;

  await queue.add(
    "trial-milestone",
    { rule: event.rule.name, customerId },
    { jobId: event.id },   // at-least-once delivery
  );
});

async function handleTrialMilestone({ rule, customerId }) {
  const customer = await db.customers.find(customerId);

  // Someone who already upgraded should not get "3 days left".
  if (!customer || customer.plan !== "trial") return;

  switch (rule) {
    case "7 days left":
    case "3 days left":
    case "1 day left":
      return sendReminder(customer, rule);
    case "Trial ended":
      return downgrade(customer);
  }
}

Reminder email

// The reminder email, with the customer's own countdown in it.
const outputs = await call(`/timers/${customer.trialTimerId}/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 renders when they open the message — so an email sent
// this morning and read tonight shows tonight's remaining time.

extendTrial

// Support extends a trial by a week. One PATCH, and every
// surface updates: the in-app banner, the hosted page, the GIF
// in an email they have not opened yet, and the expiry webhook.
export async function extendTrial(customer, extraDays) {
  const timer = await call(`/timers/${customer.trialTimerId}`);

  return call(`/timers/${customer.trialTimerId}`, {
    method: "PATCH",
    headers: { "If-Match": String(timer.revision) },
    body: JSON.stringify({
      duration_seconds: timer.duration_seconds + extraDays * 86400,
    }),
  });
}