​

Stripe decides Retention billing transitions; staff arrangements hold them

Status: accepted Date: 2026-10-19

​

Decision

1. Every billing reconciliation plans one row of the transitions table below for the Retention card. It saves the plan on retentionBillingState.planned on every run, and writes to the CRM only when RETENTION_BILLING_WRITES_ENABLED is true. The flag covers billing only. RETENTION_CRM_WRITES_ENABLED still gates the staff stage picker, tag sync and review writes.
2. The plan is a pure function, planRetentionBilling in lib/retentionBilling.ts. The card move it needs comes from billingStageTarget. The Convex action only reads, plans, guards and writes.

   Row	Stripe facts	Billing status / next bill / paid-through	Stage
   1	Trialing, no paid service on this plan yet	Trial — new customer / trial end / last paid invoice	Unchanged
   2	Active, renewing, nothing owed; or trialing after this plan paid for service (a trial extension)	Active — paying / next bill / last paid invoice, or the trial end for an extension	Unchanged, or restored from the app’s Critical
   3	past_due, unpaid or an open invoice	Past due / next bill / last paid invoice	Critical, saving the prior stage
   4	Collection paused	Paused / next bill if it resumes first, else blank / last paid invoice, or kept when open-ended	Unchanged
   5	Monthly plan, cancellation ahead	Canceled / blank / service end	Unchanged
   6	Ended, the Denver day after service end	Canceled / blank / service end	Churned + lost, saving the prior stage
   7	Canceled with money owed	Same as rows 5 and 6; open invoices on a canceled subscription are void	As rows 5 and 6
   8	An arrangement label	Not written while in force	Unchanged
   9	Yearly plan ending	Review: “Annual plan: set Paid through.”	Unchanged
   10	New subscription after a churn	Review: a fresh onboarding	Unchanged until staff reopen the card

   An unlinked card (row 11) is never planned.
3. Service end is the latest of Stripe’s end date, the latest paid invoice period and any workspace paid-through arrangement. It is compared as a calendar day in America/Denver. The account churns the day after.
4. Arrangement labels are staff-owned billing status values:
   • Complimentary holds indefinitely. Review when Stripe shows a paid, renewing plan or a missed payment.
   • Billing deferred holds until Stripe bills on or after the card’s next billing date. A missed payment ends the hold as row 3; a payment on or after that date ends it as row 2. Review when the date is blank, or when it has passed with no bill.
   • Paid through holds until the card’s paid-through date passes, then goes to review to renew or churn.
5. One writer per transition, and every write is guarded.
   • Onboarding runner: creates the card and moves it to Ramp.
   • Engine (usage): Ramp → Engaged or At Risk, At Risk ↔ Engaged, At Risk → Critical.
   • App (billing): → Critical, the restore from it, and → Churned + lost.
   • Staff: any stage through the picker, the arrangement labels and the Hold fields.
   • CRM workflows only react, through notifications or tasks.
   Before each billing dispatch, the app saves the stage it moves from and the stage it moves to (crmBeforeStageId, crmBeforeStatus, crmMoved). It restores only a card still at crmMoved, and from Critical only on row 2: any other row or review keeps the card and its baseline. A card staff moved since then is theirs, and the restore waits for review. The final read before dispatch must still show the card’s stage and the three billing fields the plan was made from.

​

Context

Staff were setting the billing fields and Churned stage by hand from Stripe. The reconciliation already read Stripe every fifteen minutes for every linked card. It wrote only a partial projection and treated a cancellation with an open invoice as past due. A churn was keyed to an exact timestamp rather than the day staff and customers use. Two live trials failed with no recorded reason. FM-2888 recorded these decisions between 2026-10-17 and 10-19:

• Q1: Critical with restore.
• Q2: Churn on the Denver day after service end.
• Q3: Canceled with money owed is not Past due.
• Q4: An annual term end goes to review.
• Q5: A restart goes to review.
• Q6: A billing-only flag.
• Q7: Hold Status and Hold Until stay staff fields.

​

Considered options

• Keep billing behind RETENTION_CRM_WRITES_ENABLED. Rejected: that flag also turns on the stage picker, tag retry and an hourly Slack tag sync for every owner. Billing needs its own shadow period and off switch.
• Treat a past-due owner as churn risk only, with no stage move. Rejected (Q1): staff work from the Critical column. The restore baseline makes the move reversible.
• Churn at Stripe’s exact end time. Rejected (Q2): it would churn an account in the evening of the last paid Mountain day.
• Churn an annual plan automatically. Rejected (Q4): annual terms are negotiated, and staff set Paid through instead.
• Restore a churned account when any subscription starts. Rejected (Q5): a new subscription is a fresh onboarding, not the old relationship resuming.
• Write arrangement labels from Stripe. Rejected: they record agreements Stripe cannot see. The app reads them and goes to review when Stripe contradicts or outlasts them.

​

Consequences

• Rollout is shadow first. Merging changes nothing in the CRM until the flag is set. Every run stores its plan, so a read-only plan-versus-CRM diff can gate the flag. Unsetting the flag stops writes on the next run.
• Billing review lists every planned transition that needs staff, and every card whose fields or stage differ from the plan. In shadow, this includes every planned move.
• A refresh failure keeps the earlier safeguards and records a scrubbed, 200-character reason.
• A restore baseline from before this change (Churned only, crmChurnStageId) is still honoured.
• Known gaps, accepted for phase 1:
  • A card staff moved out of the app’s Critical stays in review until it reaches the saved stage.
  • A refunded paid invoice still extends service to its period end.
  • A restarted account whose card staff already reopened skips the Critical move for one run.