Skip to content

Open source alternative to Semrush and Ahrefs

Instrument the fix-payment funnel and document the Loops dunning settings (#721)

Ben Senescue59b796235aa
diff --git a/docs/maintainers/billing-lifecycle-emails.md b/docs/maintainers/billing-lifecycle-emails.md
new file mode 100644
index 00000000..b33b6007
--- /dev/null
+++ b/docs/maintainers/billing-lifecycle-emails.md
@@ -0,0 +1,66 @@
+# Billing lifecycle emails: operations
+
+Design lives in `specs/0015-billing-lifecycle-emails.md`. This note covers
+what the spec leaves out: how to measure the flow, the Loops-side settings
+that are not in code, and the one-off backfill.
+
+## Fix-payment funnel
+
+Events, in order. All carry the user as distinct id and the organization as
+the PostHog group, so a funnel can be broken down by plan or by organization.
+
+| Step | Event | Where | Properties |
+| ---- | ----------------------------------- | ---------------------------------------------------- | -------------------------------- |
+| 1 | `billing:payment_failed_email_sent` | server, when the webhook sends the Loops event | `plan_id` |
+| 2 | `billing:fix_payment_viewed` | client, first ready render of `/billing/fix-payment` | `past_due`, `can_manage_billing` |
+| 3 | `billing:fix_payment_portal_opened` | client, portal button click | |
+| 4 | `billing:fix_payment_returned` | client, first ready render after Stripe returns | `past_due`, `can_manage_billing` |
+| 5 | `billing:payment_fixed` | client, return flow resolved to not past due | |
+
+Email delivery, opens and clicks are in Loops, not PostHog. Step 1 to step 2
+is therefore the email's click-through; Loops has the open rate in between.
+
+Failures, as PostHog exceptions with a `context` property:
+
+- `fix_payment_open_portal`: the Stripe portal session could not be created.
+- `fix_payment_check_timeout`: thirty seconds after returning from Stripe the
+ subscription was still past due. Every occurrence is worth a look. Compare
+ its count to `billing:payment_fixed` to see whether Stripe retries promptly
+ on card update or whether people need the "pay it in the portal" nudge.
+
+Session replay is on for the page, inputs masked. Filter replays by the
+`billing:fix_payment_viewed` event to watch real attempts.
+
+To build the funnel in PostHog: Insights, Funnels, steps 1 through 5 above,
+conversion window 14 days, break down by `plan_id` on step 1. The
+step 4 to step 5 drop is the number that says whether the page copy is doing
+its job.
+
+## Loops workflow settings that are not in code
+
+Set these in the Loops dashboard on the "Billing: Payment failed" workflow.
+The API cannot start workflows or edit their steps, so they were not applied
+automatically.
+
+1. **Filter at send time.** Add an audience filter before the email:
+ `billingState` equals `past_due`. The webhook writes that property on every
+ member before it sends the event, and the backfill script does the same,
+ so a customer who fixed their card between the event and the send is
+ dropped. Without this the filter is only on who receives the event, not on
+ who is still past due when the email goes out.
+2. **Second touch.** After the email, add a 48 hour timer, then the same
+ `billingState` equals `past_due` filter, then a resend of the email with a
+ shorter subject. Most recovered payments in dunning flows come from the
+ second touch. The filter means anyone who fixed it in the meantime does
+ not get nagged.
+
+The "Billing: Subscription started" workflow already filters on
+`billingState` equals `active` before its one week check-in; keep that.
+
+## Backfill
+
+Customers whose subscription, failed payment, or cancellation predates this
+feature were handled once with a local script that read live Autumn and sent
+the same Loops events with stable idempotency keys, writing each contact's
+billing properties first so the workflow filters above applied. It is not in
+the repository; the webhook owns everything from deploy onward.
diff --git a/src/routes/_app/billing_.fix-payment.tsx b/src/routes/_app/billing_.fix-payment.tsx
index 597ce331..84d6d33d 100644
--- a/src/routes/_app/billing_.fix-payment.tsx
+++ b/src/routes/_app/billing_.fix-payment.tsx
@@ -1,9 +1,13 @@
import { createFileRoute, Link, notFound } from "@tanstack/react-router";
import { useCustomer } from "autumn-js/react";
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
import { useSession } from "@/lib/auth-client";
import { isHostedClientAuthMode } from "@/lib/auth-mode";
-import { useCanManageBilling } from "@/client/features/team/organizationQueries";
+import { useQuery } from "@tanstack/react-query";
+import {
+ organizationContextQueryOptions,
+ useCanManageBilling,
+} from "@/client/features/team/organizationQueries";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { captureClientError, captureClientEvent } from "@/client/lib/posthog";
import { getBillingRouteState } from "@/client/features/billing/route-state";
@@ -37,11 +41,16 @@ function FixPaymentPage() {
const [isOpeningPortal, setIsOpeningPortal] = useState(false);
const [error, setError] = useState<string | null>(null);
const [checkingTimedOut, setCheckingTimedOut] = useState(false);
+ const viewCaptured = useRef(false);
const customerQuery = useCustomer({
queryOptions: { enabled: Boolean(session?.user?.id) },
});
const canManageBilling = useCanManageBilling();
+ // The hook above reports true while the role loads (a UI choice); the
+ // telemetry waits for the real role.
+ const roleResolved =
+ useQuery(organizationContextQueryOptions()).data !== undefined;
const routeState = getBillingRouteState({
hasSession: Boolean(session?.user?.id),
@@ -79,6 +88,17 @@ function FixPaymentPage() {
};
}, [isChecking, refetchCustomer]);
+ // Funnel: viewed -> portal_opened -> returned -> payment_fixed. Each fires
+ // once per page load; `returned` is a full navigation back from Stripe.
+ useEffect(() => {
+ if (routeState !== "ready" || !roleResolved || viewCaptured.current) return;
+ viewCaptured.current = true;
+ captureClientEvent(
+ returned ? "billing:fix_payment_returned" : "billing:fix_payment_viewed",
+ { past_due: isPastDue, can_manage_billing: canManageBilling },
+ );
+ }, [routeState, roleResolved, returned, isPastDue, canManageBilling]);
+
useEffect(() => {
if (returned && routeState === "ready" && !isPastDue) {
captureClientEvent("billing:payment_fixed");
@@ -88,6 +108,7 @@ function FixPaymentPage() {
async function openPortal() {
setError(null);
setIsOpeningPortal(true);
+ captureClientEvent("billing:fix_payment_portal_opened");
try {
const returnUrl = new URL(window.location.href);
returnUrl.searchParams.set("returned", "true");
diff --git a/src/server/billing/loops-sync.ts b/src/server/billing/loops-sync.ts
index f5dcd75f..dac0de61 100644
--- a/src/server/billing/loops-sync.ts
+++ b/src/server/billing/loops-sync.ts
@@ -8,6 +8,7 @@ import {
updateLoopsContact,
} from "@/server/email/loops-client";
import { sha256Hex } from "@/server/lib/audit/ids";
+import { captureServerEvent } from "@/server/lib/posthog";
import { getOptionalEnvValue } from "@/server/lib/runtime-env";
import type { BillingCustomerStatusSnapshot } from "./customer-status-model";
import type { BillingLifecycleEvent } from "./lifecycle-events";
@@ -45,11 +46,26 @@ export async function syncBillingStatusToLoops({
};
for (const contact of contacts) {
+ // Properties first: the Loops workflows filter on `billingState` before
+ // sending, so the contact must already read past_due/active when the
+ // event arrives.
+ await updateLoopsContact({
+ apiKey,
+ payload: {
+ email: contact.email,
+ userId: contact.userId,
+ userGroup: "app-user",
+ ...getContactNameParts(contact.name),
+ ...billingProperties,
+ },
+ logContext,
+ });
+
const canManageBilling = hasOrgPermission(contact.role, {
billing: ["manage"],
});
for (const event of canManageBilling ? events : []) {
- await sendLoopsEvent({
+ const { duplicate } = await sendLoopsEvent({
apiKey,
idempotencyKey: `${event.name}:${await sha256Hex(
`${snapshot.organizationId}:${contact.userId}:${previousSyncedAt}`,
@@ -62,19 +78,18 @@ export async function syncBillingStatusToLoops({
},
logContext,
});
+ // Top of the fix-payment funnel, joined in PostHog with the page's
+ // viewed/portal_opened/returned/payment_fixed events. A webhook retry
+ // that Loops deduplicated sent no email, so it does not count.
+ if (event.name === "payment_failed" && !duplicate) {
+ await captureServerEvent({
+ distinctId: contact.userId,
+ event: "billing:payment_failed_email_sent",
+ organizationId: snapshot.organizationId,
+ properties: { plan_id: event.planId },
+ });
+ }
}
-
- await updateLoopsContact({
- apiKey,
- payload: {
- email: contact.email,
- userId: contact.userId,
- userGroup: "app-user",
- ...getContactNameParts(contact.name),
- ...billingProperties,
- },
- logContext,
- });
}
}
diff --git a/src/server/email/loops-client.ts b/src/server/email/loops-client.ts
index cdf52270..1106d5b3 100644
--- a/src/server/email/loops-client.ts
+++ b/src/server/email/loops-client.ts
@@ -48,7 +48,8 @@ type LoopsEventPayload = {
/** Sends a Loops event, which triggers any workflow listening for it. Loops
* honours the idempotency key for 24 hours and answers a replay with 409,
- * which is a success here: the email was already queued. */
+ * which is a success here: the email was already queued. Returns whether
+ * this call was such a replay. */
export async function sendLoopsEvent({
apiKey,
payload,
@@ -60,7 +61,7 @@ export async function sendLoopsEvent({
idempotencyKey: string;
logContext?: Record<string, unknown>;
}) {
- await loopsRequest({
+ const status = await loopsRequest({
apiKey,
method: "POST",
url: LOOPS_EVENT_SEND_URL,
@@ -70,6 +71,7 @@ export async function sendLoopsEvent({
label: "send Loops event",
logContext: { ...logContext, eventName: payload.eventName },
});
+ return { duplicate: status === 409 };
}
async function loopsRequest({
@@ -103,7 +105,7 @@ async function loopsRequest({
});
if (response.ok || okStatuses.includes(response.status)) {
- return;
+ return response.status;
}
const errorPayload = await response.json().catch(() => null);