Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
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.mdnew file mode 100644index 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.tsxindex 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.tsindex 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.tsindex 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);