Subscriptions

Lifecycle States

                  ┌──► failed (after 60 min pending)
pending ──► active ──► expired
               │
               ├──► canceled (at period end)
               │
trialing ──► active (on payment)

none ──► (no subscription record exists)

Effective Status

BirrJS computes a runtime effective status that may differ from the stored database status:

This is handled by getEffectiveStatus():

const effective = getEffectiveStatus(subscription);
// "pending" | "active" | "canceled" | "failed" | "expired" | "none"

Subscription Flow

// Paid plan
const result = await client.subscribe({ planId: "pro" });
// result.checkoutUrl → redirect to Chapa checkout
// or result.paymentInstructions → show bank channels (Vodit)

// With trial
const result = await client.subscribe({
  planId: "pro",
  useTrial: true,
  fingerprint: await collectFingerprint(),
});
// result.trialEndsAt → trial started

const result = await birrjs.subscribe({
  customerId: "user_123",
  planId: "pro",
});
// result.checkoutUrl → return to client for redirect

// User clicks "Pay now" → Chapa checkout
const { checkoutUrl } = await client.subscribe({ planId: "pro" });
window.location.href = checkoutUrl;
// After payment, Chapa webhook activates the subscription

// User clicks "Pay now" → get bank channels
const { paymentInstructions } = await client.subscribe({ planId: "pro" });
// User pays and submits receipt
await client.verifyReceipt({ subscriptionId, receiptUrl });

// Active subscription: cancel at period end (keeps access until paid period ends)
await client.cancelSubscription({ subscriptionId });
// status stays "active", endedAt = expiresAt

// Pending subscription (never activated): cancels immediately
// status → "canceled", endedAt = now

Subscribe Input

Result Shape

If checkoutUrl is set, the subscription stays in pending until the provider confirms payment via webhook. If paymentInstructions is set, the user pays manually and submits their receipt via verifyReceipt. If trialEndsAt is set, the subscription is in trialing status with free access until that date.

Reminders

Subscriptions approaching expiry can trigger reminders via the "subscription.reminder" event. A daily cron sweep checks for subscriptions expiring on the exact days listed in reminderLeadDays and fires the event. A dedup table prevents duplicate sends.

A subscription expiring June 20 with reminderLeadDays: [7, 3, 1] gets reminders on June 13, June 17, and June 19. Each event includes daysUntilExpiry so your handler can customize per day.

createBirr({
  scheduling: {
    reminderSweepCron: "0 8 * * *",   // daily at 8am
    reminderLeadDays: [7, 3, 1],      // send 7, 3, and 1 day before
  },
  on: {
    "subscription.reminder": async (payload) => {
      await resend.emails.send({
        to: payload.customerEmail,
        subject: `Your ${payload.planName} expires in ${payload.daysUntilExpiry} days`,
        text: `Renew: https://myapp.com/renew?sid=${payload.subscriptionId}`,
      });
    },
  },
  plugins: [
    afromessage({
      messages: {
        subscriptionReminder: "{daysUntil} days left. Renew now!",
      },
    }),
  ],
});

Reminder records are automatically cleared when a subscription is reactivated, so renewed subscriptions get fresh reminders for the new period.

Cron Sweeps

The scheduler runs automatically by default (mode: "auto"). You can set mode: "external" and call the cron endpoints manually, or mode: "manual" to never run cron.

Webhook Idempotency

Webhooks are deduplicated using a unique index on (providerId, providerReferenceId). If a webhook is received twice, the second one is skipped.