Prototype

I built a single HTML file you can open by double-clicking: subscription-states.PROTOTYPE.html. I haven't opened it in a browser myself, so do a quick click-through before the meeting.

How it handles your two open questions: I didn't pick an answer for either one. Each is a switch at the top of the page, and when you flip one, everything clicked so far replays under the new rule. That way you and your PM can compare both answers on the same scenario side by side.

• Q1, the first charge fails at trial end: either grace period (→ past due) or cancel immediately (they never paid).
• Q2, a late payment on a canceled subscription: never reactivate (refund instead), reactivate only if we canceled them for not paying, or always reactivate.

What's on the page:

• Current-state panel: shows status, whether they can use the product, whether they've ever paid, whether the first charge is still pending, failed attempts, why they were canceled, and how many refunds we owe. Fields that just changed are highlighted, and every event comes with a plain-English explanation.
• Seven guided scenarios:
  • Happy path
  • Card declined at trial end
  • Decline arrives before the "trial ended" signal (payment systems don't guarantee the order events arrive in)
  • Late payment after we canceled them
  • Late payment after they canceled
  • Grace-period timer fires after they already paid
  • Events that should do nothing
• Free-play buttons: one per event. If a button would be ignored in the current state it's shown outlined, and clicking it explains why.

Things the prototype brings up that you should discuss:

• Q1 is about two things, not one. In my model, "trial ended" moves the customer to active before the first charge has resolved. So for a short time an "active" customer may never have paid. I track that with a "waiting on first charge" flag, since you only have four states. Decide whether that's acceptable or whether you need a fifth state.
• Event order matters for Q1. If the payment failure arrives before "trial ended," I treat it as the trial-end charge. The late "trial ended" is then ignored, so the customer ends up in the same place either way. Check that this is what you want.
• Q2 depends on why they were canceled. If you choose "never reactivate," you also need a refund process, because the money has already been taken. The model can only tell "customer asked" apart from "stopped paying" because it records a cancel reason, so whichever option you choose, keep that field.
• The two switches affect each other. With Q1 set to "cancel immediately" and Q2 set to "only if we canceled them," a customer who fixes their card after a failed trial-end charge comes straight back. That's probably fine, but it's worth noticing.

My recommendation: Q1 = grace period, Q2 = reactivate only for non-payment cancellations. These are the defaults the page opens with. It's your call with your PM, though.

The state logic is a self-contained SubscriptionModel block in the file. It doesn't touch the page, so you can move it into real code once you've decided. This folder isn't a git repository, so I haven't saved the prototype to a branch.