# Billing Plans Management UI **Date:** 2026-05-31 **Status:** Draft **Spec:** 124 **Tier:** All tiers **Depends on:** `billing-module`, `customers-module`, `projects-module`, `invoices-core`, `foundation-auth-rbac` **Referenced by:** `billing-module`, `customers-module` --- ## Overview Spec 18 (`billing-module`) defines `payment_methods`, `payment_plans`, and `payments` tables plus the recurring charge cron. This spec adds the complete UI for creating, managing, and monitoring payment plans — the missing frontend for spec 18's backend. --- ## Routes ``` /billing/plans → all payment plans across customers /customers/:id/billing → customer-specific payment plans (tab on customer detail) ``` --- ## Payment Plans List (`/billing/plans`) ``` ┌──────────────────────────────────────────────────────────────┐ │ Payment Plans [+ New Plan] │ │ │ │ Status: [All ▾] Customer: [All ▾] Project: [All ▾] │ │ │ │ Customer Project Amount Status Next │ │ ───────────────────────────────────────────────────────── │ │ Acme Corp Website ₪2,000/mo ACTIVE Jun 1 │ │ Dana Cohen — ₪500/mo ACTIVE Jun 15 │ │ Yossi Ltd App Dev ₪5,000/mo PAUSED — │ │ Rami Mizrahi Support ₪800/mo ACTIVE Jun 3 │ │ │ │ 4 plans · ₪8,300/mo total active │ └──────────────────────────────────────────────────────────────┘ ``` Columns: Customer, Project (optional), Amount + frequency, Status badge, Next charge date. Status badges: `ACTIVE` (green), `PAUSED` (amber), `CANCELLED` (muted). --- ## Create Payment Plan — Sheet **[+ New Plan]** → right-side sheet: ``` ┌──────────────────────────────────────────────────────────────┐ │ New payment plan [✕] │ │ │ │ Customer * [Search customers___________] │ │ Project [Link to project (optional)__] │ │ │ │ Billing cycle * [Monthly ▾] │ │ Amount * [₪__________] │ │ Day of month [1st ▾] (for monthly plans) │ │ │ │ Start date * [01/06/2026] │ │ End date [Ongoing ▾] or [Pick date] │ │ │ │ Payment method * [+ Add card] or [Select saved card ▾] │ │ │ │ Auto-invoice ☑ Generate invoice automatically │ │ Auto-send ☐ Email invoice to customer │ │ │ │ [Cancel] [Create plan] │ └──────────────────────────────────────────────────────────────┘ ``` **Billing cycle options:** Monthly, Weekly, Bi-weekly, Quarterly, Annual. **Payment method:** Saved card/mandate from `payment_methods` for this customer, or flow to add new (opens provider-specific tokenization form in modal — spec 18 mandate flow). --- ## Plan Detail View (click row) Sheet opens showing plan details + payment history: ``` ┌──────────────────────────────────────────────────────────────┐ │ Acme Corp — Website Retainer [✕] │ │ │ │ ₪2,000 / month · Active · Since Jan 1, 2026 │ │ │ │ Next charge: Jun 1, 2026 │ │ Payment method: Visa ••4242 │ │ │ │ [Pause plan] [Edit] [Cancel plan] │ │ │ │ Payment history │ │ ────────────────────────────────────────────────────────── │ │ May 1 ₪2,000 Paid INV-0051 [View invoice] │ │ Apr 1 ₪2,000 Paid INV-0038 [View invoice] │ │ Mar 1 ₪2,000 Failed → Retried Mar 3 → Paid │ │ Feb 1 ₪2,000 Paid INV-0022 [View invoice] │ └──────────────────────────────────────────────────────────────┘ ``` Each payment row links to the auto-generated invoice. Failed payments show retry badge. --- ## Plan State Transitions ``` ACTIVE → [Pause] → PAUSED PAUSED → [Resume] → ACTIVE ACTIVE → [Cancel] → CANCELLED (confirmation required: "This will stop all future charges") ``` Cancelled plans are read-only. Payment history retained. --- ## Customer Billing Tab On `/customers/:id` detail page, add **Billing** tab alongside Overview/Projects/Invoices: ``` ┌──────────────────────────────────────────────────────────────┐ │ Overview Projects Invoices Billing Portal │ │ │ │ Payment methods [+ Add card] │ │ ────────────────────────────────────────────────────────── │ │ Visa ••4242 Exp 08/2027 [Default] [Remove] │ │ │ │ Active plans [+ New plan] │ │ ────────────────────────────────────────────────────────── │ │ Website Retainer ₪2,000/mo ACTIVE Next: Jun 1 │ └──────────────────────────────────────────────────────────────┘ ``` --- ## Add Payment Method Flow When creating a plan or managing customer payment methods: 1. Click **[+ Add card]** → opens modal 2. Modal embeds provider tokenization UI (hosted iframe/redirect per spec 18 adapter): - **Morning/Cardcom/Payplus**: hosted payment page redirect; return with `provider_token` - **Isracard direct debit**: mandate form PDF download + mandate reference input 3. On success: `payment_methods` row created; modal closes; method appears in dropdown --- ## API (uses spec 18 endpoints) No new API endpoints. All actions use spec 18 routes: ``` POST /api/billing/plans → create plan PATCH /api/billing/plans/:id → edit/pause/resume DELETE /api/billing/plans/:id → cancel plan GET /api/billing/plans → list (query: customer_id?, project_id?, status?) GET /api/billing/plans/:id/payments → payment history POST /api/billing/payment-methods → save tokenized method DELETE /api/billing/payment-methods/:id → remove ``` --- ## Architecture Decisions | Decision | Choice | Reason | |----------|--------|--------| | `/billing/plans` + customer tab | Not only in customer detail | Operations staff need cross-customer plan overview; finance team needs `/billing/plans` for monthly revenue view | | Sheet for create/detail | Not full page | Plans are supplementary to customers/projects; sheet keeps context | | Provider-hosted tokenization | Not own CC form | PCI compliance; all Israeli gateways require their own hosted tokenization form | | Link payment to invoice | Not payment as standalone | Every auto-charge should create an auditable invoice; Israeli law requires receipt; links in payment history make reconciliation easy |