💳 Billing Engine & Pricing Architecture

This developer guide provides an technical analysis of the billing engine, proration algorithm hook (useUpgradeCalculations), wallet top-up integration, and pricing page state machines (useSubscriptionLogic).

---

🧮 1. Proration & Upgrade Hook (hooks/use-upgrade-calculations.ts)

The useUpgradeCalculations hook calculates real-time upgrade totals, unused plan credits, add-on credit rollovers, and NGO percentage discounts.

Hook Signature & Output Schema

export function useUpgradeCalculations(props: UseUpgradeCalculationsProps) {
  // 1. Calculate Remaining vs Total Cycle Days (30 vs 365)
  // 2. Compute Unused Current Plan Credit
  // 3. Compute Active Add-on Credit Rollover
  // 4. Calculate New Plan Base Cost & New Extra Add-ons
  // 5. Return Net Amount to Pay & Stored Wallet Credit
}

Core Proration Algorithm Code

Below is the exact mathematical execution block used when computing unused credits:

// 1. Unused Plan Credit Formula
const unusedValue = isCurrentPlanFree
  ? 0
  : (remainingDays / currentCycleTotalDays) * currentTotalValue;

// 2. Unused Extra Add-ons Credit Formula
const currentAddonsTotalValue =
  locVal.quantity * locVal.price +
  deptVal.quantity * deptVal.price +
  schVal.quantity * schVal.price +
  hrtVal.quantity * hrtVal.price +
  otherAddonsValue;

const unusedExtraAddons =
  (remainingDays / currentCycleTotalDays) * currentAddonsTotalValue;

// 3. Net Amount to Pay
const amountToPay = newTotalFullCost - unusedValue - unusedExtraAddons;
const isCreditRemaining = amountToPay < 0;
const finalPayment = isCreditRemaining ? 0 : amountToPay;

---

🏷️ 2. Pricing Logic Store & State Machine (hooks/use-subscription-logic.ts)

On /pricing and /billing, the useSubscriptionLogic hook processes plans to derive contextual button states (isCurrent, isUpgrade, isPayNow, buttonLabel):

export function useSubscriptionLogic(
  plans: PlanData[],
  activeSubscription: Subscription | null,
  billingCycle: "monthly" | "yearly"
) {
  const processedPlans = useMemo(() => {
    return plans.map((plan) => {
      const isCurrent = activeSubscription?.plan_id === String(plan.id);
      const isUpgrade =
        !isCurrent &&
        Number(plan.price || 0) > Number(activeSubscription?.plan?.price || 0);

      let buttonLabel = "Subscribe";
      if (isCurrent) buttonLabel = "Current Plan";
      else if (isUpgrade) buttonLabel = "Upgrade Plan";

      return {
        ...plan,
        metadata: {
          isCurrent,
          isUpgrade,
          buttonLabel,
        },
      };
    });
  }, [plans, activeSubscription, billingCycle]);

  return { processedPlans };
}

---

💳 3. Payment Execution Services (hooks/https/payment.ts)

• useInitializePayment(gateway): Initializes online payment transactions via gateway proxies.
• useBuyWithWallet(): Executes instant wallet deductions for subscriptions or add-on purchases.
• useUpgradeWithWallet(): Executes plan tier upgrades directly funded by organization prepaid wallet balances.
• useConvertTrial(): Converts an active free trial into a paid subscription using wallet funds.