Evergreen farms (pos)

Private

Tracker *Bug Feature Support Testing

Subject *

Description Edit h3. Background & Business Objective Currently, tenants manage payment methods, billing details, and plan status either by redirecting to Stripe's hosted portal (`billing.stripe.com`) or by contacting administrators. While Stripe's hosted portal handles card security, it: 1. Navigates the customer away from our application, creating a disjointed user experience. 2. Does not capture exit feedback or cancellation reasons when a customer decides to churn. 3. Gives our platform zero policy control over whether self-service cancellation is permitted or restricted to admin approval without manual Stripe merchant dashboard toggling. This task introduces a dedicated, fully white-labeled *Customer Billing & Subscription Hub* inside both Evergreen POS (`/settings/billing`) and Connect Super Admin (`/app/tenants/:id/billing`), unifying plan visibility, invoice history, payment updates, and an intelligent in-app cancellation workflow. h3. Scope & Key Features 1. *Unified White-Label Billing Hub (Shared UI for Tenant & Super Admin):* * Clean overview displaying: * Active plan name, billing interval (monthly/yearly), next renewal date, and renewal amount. * Real-time billing status badge (*Active*, *Past Due*, *Grace Period*, *Canceling soon*, *Suspended*). * Card on file summary (Brand icon, last 4 digits, expiration date). * Comprehensive Invoice & Billing History table with direct PDF receipt download. 2. *Super-Admin-Controlled Self-Cancellation Policy:* * Introduce a platform-level configuration toggle: `allowTenantSelfCancellation` (Boolean). * *When Enabled (`true`):* Tenant sees an in-app "Cancel Subscription" button. * *When Disabled (`false`):* Replaces the cancellation button with a courteous *"Need to change or cancel your plan? Contact your Account Manager"* CTA to prevent unwanted churn and accidental POS shutdowns. 3. *In-App Cancellation Modal with Churn Feedback Survey:* * If self-cancellation is enabled, clicking "Cancel Subscription" triggers an in-app survey modal: * Reason for leaving (Dropdown: *Seasonal business closure*, *Switched to another provider*, *Missing features*, *Pricing/Budget*, *Other*). * Optional comments/feedback textarea. * Effective date selection (Default: *End of current billing cycle* vs *Immediate* for admins). * Automatically persists the feedback, cancellation reason, and actor tag into `company.saasBillingActionHistory`. * Sends automated notification to Super Admin with customer exit feedback. 4. *Secure Hybrid Payment Method Update:* * When updating credit/debit card details, provides a dedicated "Update Card" action that launches a focused Stripe card update session without exposing the generic Stripe cancellation options. * Maintains 100% PCI-DSS compliance with zero cardholder data liability on our servers. 5. *In-App Retention & Pause Offer (Optional Churn Reduction):* * For seasonal businesses (e.g. landscaping/nurseries in winter), present a "Pause Subscription" or "Seasonal Hold" option before final cancellation confirmation. h3. Technical Architecture & Endpoints * *Backend (`evergreen_pos_be`):* * Extend `POST /api/v1/superadmin/billing/cancel` to accept `{ reason, feedback, actor }` and log structured metadata to `saasBillingActionHistory`. * Add `GET /api/v1/superadmin/billing/config` and `PATCH /api/v1/superadmin/billing/config` for `allowTenantSelfCancellation`. * Ensure `tenantBilling.service.js` records the exit survey data. * *Frontend (`evergreen_pos_fe` & `nexZentekSubscription_fe`):* * `CustomerBillingHub.tsx`: Reusable subscription and billing overview card. * `CancelSubscriptionModal.tsx`: Churn feedback survey modal. h3. Business Value & Acceptance Criteria * *Brand Consistency:* 100% white-labeled experience keeping tenants inside the Evergreen platform. * *Churn Insights:* Every cancellation records rich feedback explaining *why* the customer left. * *Operational Safety:* Prevents accidental store shutdowns by allowing Super Admins to govern cancellation policies. * *Audit Compliance:* All actions (who cancelled, why, and when) are queryable in the tenant's billing audit timeline.