cocottetech/@platform/codebase/@features/ai-copilot/docs/Z-billing-payments.brief.md

Z — Billing + payments UX (P5+)

Goal

Define the UX for the two distinct money-flows that touch CocotteAI: Quinn-pays (her CocotteAI subscription + metered LLM costs) and Quinn-receives (deposits from prospects via Venmo / Cash App / WishTender / Throne — the N5 commerce surfaces in brief O). Both are deferred to P5+ by plan; until then platform.db tracks usage but no billing rendering ships. This brief is pre-design so the schema decisions made now (usage counters, per-specialist cost attribution, per-org payment ownership) stay forward-compatible.

The voice register here is plain throughout — financial matters are operational, not ambient. No "stockpot" or "simmering" near money. Working register is allowed for upgrade prompts and grace-period copy; hearth is banned.

Designer skim

• Headline UX: A single settings root (Z1) shows tier · usage · cost-this-vigil · next bill · payment method. Per-feature gates (Z2) live inline at the locked feature, not in a separate paywall. Metered LLM cost (Z3) is transparent and per-specialist. Quota approach triggers a self-throttle question (Z4 — degrade / hard-stop / upgrade). Demimonde admin owns org billing (Z5). Quinn's N5 receipt providers (Z6) are configured separately and never co-mingled with subscription state.
• Sections (8): Z1 subscription tier landing · Z2 per-feature gating · Z3 metered LLM cost transparency · Z4 quota self-throttling · Z5 org-level billing · Z6 N5 commerce surface integration · Z7 receipts + invoices · Z8 failed-payment recovery.
• Pair-with: brief S §S8 privacy + S1 account (billing lives under one of these, see Z1 open Q) · brief M §M5 quota self-throttling (Z4 is the user-facing companion) · brief O §N5 commerce surfaces (Z6) · brief W (Z5 org-level) · brief T (optional cost panel).
• Blocking Qs: Z-Q1 pricing model · Z-Q2 cost transparency default · Z-Q3 quota-throttle default.

Constraints

• Plain register everywhere. Money is operational. Never "your pantry is getting full" for a quota warning; say "you're at 80% of the monthly cap." No exclamation points. No urgency theater on upgrade prompts.
• Two money-flows never co-mingle. Z1–Z5 + Z7–Z8 are Quinn-pays-CocotteAI. Z6 is Quinn-receives-from-prospects. The settings IA must make this distinction structurally — separate roots, separate receipts, separate audit trails. A user must never confuse "my subscription receipt" with "a prospect's deposit receipt."
• Cost transparency over surprise. Quinn must always be able to see what each turn cost, what each specialist cost this vigil, and what the projected month-end total looks like. No bills that arrive unexplained.
• Grace, not suspension. Failed payment → downgrade-not-suspend (Z8). CocotteAI is operational infrastructure for an income-earning business; cutting off access for a failed card is hostile. Downgrade tier, keep core auto-actions running, ask for re-payment without urgency.
• Org-billing inherits person-tenancy. Per [DESIGN §5] every billing record carries user_id (Person) and optional org_id (Org). A Demimonde-billed subscription doesn't strip Quinn's personal billing visibility — admin sees both layers.
• N5 surfaces are read-only-for-payment in P5. CocotteAI does not move money on Quinn's behalf into or out of Venmo / Cash App / WishTender / Throne. It records deposits, attaches them to prospects, and surfaces totals. Actual transfer initiation stays manual until P6+.

States to design

• Z1 tier landing — current tier · usage bars · next renewal date · upgrade / downgrade affordances · payment method row.
• Z2 feature-locked card — inline gate at the locked specialist drawer or routing affordance · "this is in tier X" copy · one-tap upgrade flow.
• Z3 cost-this-vigil chip — small chip in chat-home or audit drawer top-strip · expands to per-specialist breakdown.
• Z3 expensive-turn warning interrupt — shown before dispatching a re-route or full strategist run estimated > $X.
• Z4 quota-approach sheet — 80% banner · 95% interrupt with three options (degrade / hard-stop / upgrade).
• Z5 org-billing roster — Demimonde admin view: payment method · per-member usage · org-wide invoice history.
• Z6 N5 commerce config — per-provider connection card (Venmo / Cash App / WishTender / Throne) · last-sync · deposit count this vigil.
• Z6 deposit row — single deposit attached to a prospect with provider · amount · timestamp · prospect link.
• Z7 receipt list — paginated invoices · download PDF affordance · per-line-item drill-in.
• Z8 failed-payment banner — top-of-chat plain banner · "card failed, you're on grace until [date]" · update-card affordance.
• Z8 downgraded-tier state — chip on locked features showing "available again when payment resumes."

Z1 — Subscription tier landing (single source of truth)

One root view answers what am I paying for, what am I using, what's it costing. Lives either at Settings → Account → Billing (S §S1 row) or as its own settings root. Lean toward its own root because (a) it's frequent enough during onboarding + tier-change moments to warrant top-level, (b) Quinn-receives money (Z6) lives in a parallel root and the symmetry helps the IA. Lock open Q Z-Q1 before P5.

Layout (plain):

Billing

Tier · Steady ($49/mo)        [ Change tier ]
Next bill · Jun 14 · $49 to card ending 4242

Usage this month
  Specialists active        7 / 10 included
  LLM cost (so far)         $14.20 of $40 included
  Approval-cards dispatched 412 / unlimited
  Multi-leg routing runs    3 / 5 included

Payment method
  Visa ending 4242 · expires 06/28      [ Update ]

Receipts                                [ View all → ]
  May 14 · $49 · paid
  Apr 14 · $49 · paid
  Mar 14 · $49 · paid

Tier names are placeholder pending Z-Q1. Three tiers feels right (Quiet · Steady · Working) — see open Q.

Z2 — Per-feature gating (advanced specialists / multi-leg routing R6 / coop participation)

Locked features don't hide; they show with a lock chip and a one-tap unlock path. The gate lives at the feature, not in a separate paywall screen.

Examples:

• Specialist drawer (L) for a tier-locked specialist: drawer renders with all sections greyed plus a footer chip "prospect-resolver is in Working tier · upgrade for $20/mo · try free for 7 days."
• Multi-leg routing affordance (R §R6) on the tour-leg-detail screen: the "plan multi-leg trip" button is present but tagged with a lock glyph. Tap → small sheet: "Multi-leg routing optimizes 3+ stops at once. Steady tier or higher. Upgrade or plan legs one-by-one."
• Coop participation (N) when on a tier that excludes it: coop-drawer header shows "Reading coop intel is included. Publishing reports is in Working tier."

Card UX rules:

• Locked affordances never lie about what's behind the lock — show the feature name, not a generic "Premium."
• Upgrade flow is two taps: tier-picker sheet → confirm → return to where Quinn was, feature now active.
• Trials are offered inline when applicable (7-day on Steady → Working), not as a popup.

Z3 — Metered LLM usage transparency (Quinn-side)

CocotteAI runs through @model-boss (apricot) for most inference; some specialists call paid model APIs. Either way, cost is per-turn attributable. Surface it:

• Cost-this-vigil chip — small chip in chat-home top strip (or audit-drawer top): $2.40 today. Tap → breakdown:

  Cost this vigil · $2.40
  
    strategist        $1.10  (one full run, 14:02)
    triage            $0.42
    content-onlyfans  $0.38
    bookings-tryst    $0.12
    ai-copilot        $0.38
  

• Cost-this-month tile — in the Z1 billing root, plus a sparkline so Quinn sees trend.

• Per-specialist cost — each specialist-drawer (L) gets a small "cost this vigil / month" row under the trust meter. Helps Quinn decide if an underperforming specialist is also expensive.

• Expensive-turn warning — before dispatching a turn estimated to cost more than $X (per Z-Q2), an interrupt sheet asks confirmation:

  This turn will run the strategist on 90 days of context. Estimated cost · $1.80. Continue or scope down.

  Default threshold leans $1.00 for ad-hoc turns; auto-scheduled strategist runs don't trigger this (they're budgeted into the tier's monthly LLM allowance and visible in Z1 usage).

• Re-route cost — when Quinn requests a re-route of a tour (R) or a re-plan, the same warning applies if the estimated tokens cross threshold.

Z4 — Quota self-throttling UX (companion to M §M5)

brief M §M5 defines the self-throttle behavior in the failure-mode taxonomy: when usage approaches the monthly cap, the system slows non-critical posts. This brief defines the user-facing decision-point when the cap is genuinely near.

Thresholds (subject to Z-Q3):

• 80% banner (plain, top-of-chat, dismissible): "You've used 80% of this month's LLM allowance. Three weeks left in the cycle. Tap to see options."
• 95% interrupt (plain, modal, undismissible until a choice is made):

  You're at 95% of this month's LLM allowance ($38 of $40).
  How should I handle the rest of the cycle?
  
  ○ Slow down · keep critical actions, defer non-urgent posts
  ○ Stop · pause auto-actions, you still drive manually
  ○ Upgrade · move to Working tier, +$30/mo
  

Once a choice is made, it's logged to audit and recoverable in Z1 ("you chose 'slow down' on May 14 — change?"). Default leans slow down per Z-Q3 — preserves operational continuity without surprise charges. Choosing stop dovetails with brief M §M5's self-throttle.

The interrupt voice is plain and non-judgmental. No "uh oh!" No "you've used a lot of credits!" Just the numbers and three options.

Z5 — Org-level billing (per W org-overlay)

Per brief W, Demimonde is org-overlay over personal-Quinn. Org billing follows:

• Demimonde admin (Quinn at P5, possibly a Demimonde staff member later) owns the payment method, the tier choice, and the cycle.
• Members (other Demimonde participants in future) consume from the org's allowance. They see their own usage attributed in Z3 but cannot change tier or payment method.
• Viewers never see billing.
• The Z1 root, when scoped to org context (per brief W §W2 chip), shows the org's billing — not personal. Switching to personal context shows personal billing. No co-mingling.
• Per-member cost attribution — Z3 cost-this-month tile, under org scope, breaks down by member. Helps the admin see whether a member is dominating usage.
• Personal subscription + org subscription coexist. Quinn may have her own personal tier (her own LLM usage when she's working personal-context) and a Demimonde org tier (org-context work). Two payment methods, two billing cycles, two receipt streams.
• Org-billing invariants (cross-cut brief W §W9): a member's personal billing data is never visible to the org admin. Only org-context usage is aggregated.

Z6 — N5 commerce surface integration (Quinn-receives)

This is separate from Z1–Z5. CocotteAI doesn't bill through Venmo / Cash App / WishTender / Throne — Quinn collects deposits there.

Per-provider connection card under a parallel root (call it Settings → Income or Settings → Deposits — see Z-Q1 follow-on):

Deposits

Venmo · @transquinnftw           [ Sync now ]
  Last sync 12m ago · 3 deposits this vigil · $410

Cash App · $transquinnftw        [ Sync now ]
  Last sync 1h ago · 0 deposits this vigil

WishTender · transquinnftw       [ Connect ]
  Not connected

Throne · transquinnftw           [ Connect ]
  Not connected

Per-deposit row (when expanded):

Venmo deposit · May 18 14:02 · $150
  From: @felix.k (matched to prospect @felix · 89% confidence)
  Note: "thursday tour deposit"
  Status: confirmed
  [ Confirm match ] [ Edit match ] [ Unattach ]

Behavior:

• CocotteAI reads deposit events (via provider API where available, manual entry where not). It does not initiate payouts, transfers, or refunds. Out-of-band money movement stays Quinn's hand on the wheel.
• Each deposit is offered for prospect attachment — prospect-resolver (L) proposes a match; Quinn confirms. Attached deposits flow into brief T §T1 revenue panel.
• Trust posture: deposit-matching is propose-only (per brief I trust loop). Auto-confirm graduations happen surface-by-surface, not provider-wide.
• WishTender / Throne wishlist purchases are recorded as deposit-equivalents with the item bought and the prospect attribution.
• No tax handling. Out of scope (see below).

Z7 — Receipts + invoices

Two streams, kept separate:

Subscription receipts (Quinn-pays):

• Paginated list in Z1.
• Per-receipt drill-in: date · amount · payment method · tier · LLM-usage line item · multi-leg routing line item · any add-ons · download PDF.
• Receipts are immutable; corrections come as adjustment line items on the next cycle.
• Email delivery to Quinn's billing address (per S §S1).

Deposit receipts (Quinn-receives):

• Paginated list in Z6 root.
• Per-deposit drill-in: provider · amount · prospect attribution · note · status (pending / confirmed / disputed).
• Exportable to CSV for Quinn's own bookkeeping (out-of-scope to handle taxes inside the app).

Both streams are searchable via brief U — type:receipt / type:deposit.

Z8 — Failed payment recovery (downgrade-not-suspend)

Card declines happen. CocotteAI's response is operational, not punitive.

Flow:

1. Decline detected → silent retry once in 24h (standard processor behavior).
2. Second decline → top-of-chat plain banner: "Card ending 4242 was declined on May 18. You're on a 7-day grace period. Update card or contact support."
3. Grace period (default 7 days, configurable per tier): full tier access continues, banner persists, no feature lock-down.
4. Grace expires → downgrade to the lowest tier (Quiet · base subscription, includes core auto-actions). Feature lock chips appear per Z2 with "available again when payment resumes" copy. Quinn's data is fully preserved; only forward-looking specialist tier-gates engage.
5. Payment resumes → tier restores instantly, lock chips clear, a digest entry records the gap.

Never:

• Never lock Quinn out of her data during a failed payment. Audit drawer, prospect list, asset library, kill switch — all stay accessible.
• Never disable kill switch during a billing failure. Operator safety is independent of payment state.
• Never auto-cancel a subscription on missed payment. Quinn cancels explicitly; we only downgrade.

In-the-wild copy

Z1 next-bill row (plain):

Next bill · Jun 14 · $49 to card ending 4242

Z2 feature-locked footer chip (working):

prospect-resolver is in Working tier. Upgrade for $20/mo or try free for 7 days.

Z3 expensive-turn warning (plain):

This turn will run the strategist on 90 days of context. Estimated cost · $1.80. Continue or scope down.

Z4 95% interrupt header (plain):

You're at 95% of this month's LLM allowance ($38 of $40). How should I handle the rest of the cycle?

Z5 org-context billing chip (working):

Billing scoped to Demimonde. Personal billing is on the personal tab.

Z6 deposit confirmation (plain):

Venmo $150 from @felix.k. Match to prospect @felix? 89% confidence.

Z7 receipt drill-in line item (plain):

May 14 · $49 · Steady tier · paid

Z8 grace-period banner (plain — operational, not alarming):

Card ending 4242 was declined on May 18. You're on a 7-day grace period. Update card to keep your full tier.

Z8 downgrade notice (plain):

Tier moved to Quiet while payment is pending. Your data and core auto-actions are intact. Working tier features will return when payment resumes.

Out of scope

• Chargeback handling — separate brief. When a prospect disputes a Venmo deposit or Quinn disputes a CocotteAI charge, the workflow lives elsewhere.
• Tax forms (1099s, VAT receipts, sales tax) — separate brief, ties into export tooling and possibly a CPA-facing companion.
• Currency support beyond USD — P0–P5 is USD-only; multi-currency is post-P5.
• Refund initiation UX — admin tool, not Quinn-near.
• Org-to-org billing transfers — out of scope until cross-org sharing exists (per brief W out-of-scope).
• Per-specialist a-la-carte purchases — current model is tier-based, not feature-cart.
• Promotional codes / referral discounts — defer until a referral program exists.

Open questions

• Z-Q1 Pricing model — pure subscription tiers, pure metered (pay-per-LLM-token), or hybrid (tier with a generous monthly allowance + overage at metered rate)? Lean: hybrid — predictable monthly bill for most, no cliff for heavy months. Subscription tier includes an LLM allowance and a feature-gate set; overage bills at the next cycle. [blocking]
• Z-Q2 Cost-transparency default — is the cost-this-vigil chip shown by default for all users or opt-in? Lean: on by default, with a setting to hide in S §S2 (some users find money-near-chat anxiety-inducing; respect the choice but show by default so trust loop earns visibility). [blocking]
• Z-Q3 Quota-throttle default at 95% — degrade / hard-stop / upgrade? Lean: degrade gracefully — preserves operational continuity, surfaces the choice without preemptive charges, respects Quinn's autonomy. Hard-stop is safer-but-disruptive; upgrade-by-default is hostile. [blocking]
• Z-Q4 Billing root location — own root or under Settings → Account? Lean: own root, paired with a Deposits root (Z6). The two money-flows deserve symmetric placement and frequent-access shape. [nice-to-have]
• Z-Q5 Trial period for tier upgrades — 7 days inline trial per Z2? Universally, or only for specific high-value gates (prospect-resolver, multi-leg routing)? Lean: only for specialist-gates with proven discovery friction. [exploratory]

Related

• brief S §S8 + S §S1 — billing root placement and account-row IA.
• brief W — org-context billing inheritance (Z5).
• brief M §M5 — engineering side of quota self-throttling (Z4 is the user-facing companion).
• brief O §N5 — canonical N5 commerce surface enumeration.
• brief T — optional cost panel on the strategist's front window; deposit data feeds T1 revenue.
• brief I — deposit-match attribution flows through the trust loop.
• brief U — receipts + deposits searchable as types.
• DESIGN §5 — person-first tenancy with optional org_id; billing records inherit.