@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/_internal/server/features/checkout/actions.js

@@ -16,7 +16,18 @@ import { roundShippingUp, } from "../../../shared/shipping/quote.js";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
 import { resolveStateKey, INDIA_STATES } from "../../../shared/fees/india-states.js";
-import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
+import { allocatePointsAcrossGroups, computePreOrderDepositAmount, lineTotalFor, resolvePointsTender, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
+/*
+ * D46/D47 — points as a checkout TENDER.
+ *
+ * `storeAcceptsPoints` resolves decision 22's per-store opt-in (and the
+ * platform store's always-accepts, which is decided in code); the repository
+ * supplies the balance and owns the ledger write. The ARITHMETIC lives in
+ * `resolvePointsTender` above, beside every other money rule, so the tender
+ * cannot become a sixth disagreeing total (D37/D38/D40).
+ */
+import { storeAcceptsPoints } from "../../../shared/features/points/accepts.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
 import { COD_MAX_ORDER_VALUE_FALLBACK } from "../../../../features/admin/schemas/firestore.js";
 import { CHECKOUT_ERROR_CODES } from "../../../../errors/error-codes.js";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository.js";
@@ -31,6 +42,9 @@ import { DEFAULT_STORE_SHIPPING_POLICY, quoteShipping, toStoreShippingPolicy, }
  */
 import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 import { computeProtectionFees } from "../../../shared/features/shipping/protections.js";
+/* S5a — one payer, N destinations. Pure: the rates come in snapshotted, and
+ * an UNPRICED arrangement is refused rather than quoted at ₹0 (D44's lesson). */
+import { countDestinations, quoteSharedPurchase, } from "../../../shared/features/shipping/shared-purchase.js";
 import { resolveCouponCategorySlugs } from "../../../../features/promotions/actions/coupon-actions.js";
 import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, } from "./locked-lines.js";
 import { activeLane, defaultCheckoutItems, resolveCheckoutItems, laneOf, } from "../../../shared/checkout/lanes.js";
@@ -262,6 +276,10 @@ opts) {
             shippingPolicy: DEFAULT_STORE_SHIPPING_POLICY,
             shippingUnavailable: false,
             storeProtections: { shipping: false, sale: false },
+            // No store, so no seller to absorb a redemption.
+            acceptsPoints: false,
+            // No store, so nobody to pack N parcels.
+            sharedPurchaseRates: { allowSharedPurchase: false },
             // No store, so no seller registration — the caller falls back to the
             // platform's via resolveSupplierIdentity.
             storeTaxIdentity: undefined,
@@ -381,6 +399,13 @@ opts) {
             shipping: store?.supportsShippingProtection === true,
             sale: store?.supportsSaleProtection === true,
         },
+        acceptsPoints: storeAcceptsPoints(store, storeId),
+        // S5a — raw, so the caller can tell "not configured" from ₹0.
+        sharedPurchaseRates: {
+            allowSharedPurchase: store?.allowSharedPurchase === true,
+            sharedPurchaseHandlingFee: store?.sharedPurchaseHandlingFee,
+            sharedPurchaseExtraShippingPerDestination: store?.sharedPurchaseExtraShippingPerDestination,
+        },
         /*
          * The seller's own tax registration, returned from the store read this
          * function ALREADY does.
@@ -594,6 +619,112 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
         return;
     Promise.all(emailsToSend.map((e) => sendOrderConfirmationEmail(e))).catch((err) => serverLogger.error("Order confirmation email error:", err));
 }
+/**
+ * The buyer's points balance, or **0** if it cannot be read.
+ *
+ * 🛑 Failing OPEN to zero is the safe direction and the only safe direction: a
+ * balance we could not read becomes "no discount applied", so the buyer is
+ * charged the full amount and their points are untouched. The inverse — guessing
+ * a balance — would reduce the charge against points that may not exist, which
+ * is the shape of the deleted D46 block (it debited points and reduced nothing;
+ * this is the same mistake with the signs swapped).
+ *
+ * A buyer who opted in and sees no discount can retry. There is no recoverable
+ * outcome on the other side.
+ */
+async function safePointsBalance(userId) {
+    try {
+        return await pointsRepository.getBalance(userId);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("[checkout] points balance unreadable — charging full amount", {
+            userId,
+            error: normalized.message,
+        });
+        return 0;
+    }
+}
+/**
+ * Debit the points an order was discounted by — the second half of the tender.
+ *
+ * 🛑 ONE implementation, called from BOTH order-creation paths. They are
+ * ~200-line twins that have already drifted once (add-on fees, Root Cause
+ * #65), and a money rule reachable by copy-paste gets copied (Root Cause #75).
+ *
+ * Runs AFTER the order exists and BEFORE the gateway is asked for anything.
+ * That ordering is the whole D46 fix: the deleted block ran after capture, so a
+ * redemption that succeeded took points from a buyer who had just paid full
+ * price while its own comment claimed "the balance intact".
+ *
+ * 🛑 A REFUSED REDEEM REVERTS THE DISCOUNT; it is never swallowed. `redeem`
+ * re-reads the balance inside its own transaction and refuses rather than going
+ * negative — so a refusal means the budget was wrong and the order is recording
+ * a discount nobody funded. Reverting is the only honest response: the buyer
+ * pays full price, which they can see and query, where an unfunded discount is
+ * a silent under-collection on every order that hits it.
+ *
+ * `orderId` is the natural idempotency key — this runs once per created order,
+ * and an order is created once.
+ */
+async function settlePointsTender(input) {
+    if (input.pointsApplied <= 0)
+        return;
+    try {
+        await pointsRepository.redeem({
+            userId: input.userId,
+            points: input.pointsApplied,
+            orderId: input.orderId,
+            description: `Points applied to order ${input.orderId}`,
+        });
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.error("[checkout] points redemption refused — reverting the discount", {
+            orderId: input.orderId,
+            userId: input.userId,
+            pointsApplied: input.pointsApplied,
+            error: normalized.message,
+        });
+        // Hand the budget back, so a later group in the same checkout is not
+        // charged for a spend that did not happen.
+        input.pointsBudget.remaining += input.pointsApplied;
+        await unitOfWork.orders
+            .update(input.orderId, { pointsApplied: undefined, amountDue: undefined })
+            .catch((e) => {
+            /*
+             * 🛑 The one genuinely bad outcome, so it is reported rather than
+             * logged: the order still says `amountDue`, the points were never
+             * taken, and the gateway is about to be asked for the discounted
+             * figure. A case names the amount and the order; `safeRead`'s silent
+             * degrade would be wrong here because nothing downstream can detect it.
+             */
+            const inner = normalizeError(e);
+            serverLogger.error("[checkout] points revert FAILED — order under-collects", {
+                orderId: input.orderId,
+                amountUnfunded: input.pointsApplied,
+                error: inner.message,
+            });
+            void paymentCasesRepository()
+                .openOrObserve({
+                kind: "amount_mismatch",
+                // The problem is this order's unfunded discount, so the subject is
+                // the order — one case however many times it is observed.
+                subjectId: input.orderId,
+                severity: "error",
+                entityType: "order",
+                entityId: input.orderId,
+                orderIds: [input.orderId],
+                title: "Order carries a points discount that was never funded",
+                detail: `Redemption of ${input.pointsApplied} points was refused and the ` +
+                    `revert also failed, so this order will be captured at its ` +
+                    `discounted amountDue with no matching ledger debit.`,
+                amountAtRisk: input.pointsApplied,
+            })
+                .catch(() => undefined);
+        });
+    }
+}
 /**
  * Places one order for one seller-group of the checkout cart — fee math
  * (COD deposit/handling, EMI schedule), coupon apportionment, order-doc
@@ -602,7 +733,7 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
  * so the caller can accumulate the checkout-wide `total`.
  */
 async function createOrderForGroup(group, orderType, ctx) {
-    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, } = ctx;
+    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, useAllPoints, pointsBudget, } = ctx;
     const firstItem = group[0].item;
     const firstProduct = group[0].product;
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
@@ -650,7 +781,7 @@ async function createOrderForGroup(group, orderType, ctx) {
      * grouped line the two differ.
      */
     const groupGoodsValue = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
+    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity, acceptsPoints, sharedPurchaseRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
     /*
      * 🛑 The buyer's quote WINS over the seller's configured rate, and it is
      * re-rounded here rather than trusted as sent.
@@ -818,6 +949,47 @@ async function createOrderForGroup(group, orderType, ctx) {
             groupCouponCodes.add(discount.code);
         }
     }
+    /*
+     * ── S5a: a shared purchase — one payer, N destinations ────────────────────
+     *
+     * Computed BEFORE `orderTotal` because it is a term in it. The rates come
+     * off the store document and are SNAPSHOTTED onto the order below: a
+     * coordinator commits against a quoted total, and re-reading a rate at
+     * settle would let a seller raise it afterwards. That is D61's rule, and the
+     * precedent is the refund path reading `finalSale` from the order snapshot
+     * for exactly this reason.
+     *
+     * 🛑 `countDestinations` counts DISTINCT addresses and collapses every line
+     * with no `destinationAddressId` into one bucket — the order's own address.
+     * Counting items instead would charge an ordinary three-item order for two
+     * extra legs it never asked for.
+     */
+    const sharedQuote = quoteSharedPurchase({
+        destinationCount: countDestinations(group.map(({ item }) => item)),
+        rates: sharedPurchaseRates,
+    });
+    /*
+     * 🛑 An UNPRICED arrangement is refused, not given away. The seller opted in
+     * without setting a rate, which is not consent to do the extra packing for
+     * free — and quoting ₹0 is exactly D44: `shippingUnavailable` carried a
+     * docstring saying "the caller MUST act on this rather than trusting
+     * `shippingFee: 0`", had zero consumers, and every `estimate`-mode store
+     * shipped free on every path as a result.
+     */
+    if (sharedQuote.unpriced) {
+        throw new ValidationError("This seller has not set a price for splitting an order across addresses. " +
+            "Send everything to one address, or contact the seller.");
+    }
+    /*
+     * A multi-destination order from a store that has NOT opted in. The quote
+     * prices; it does not authorise — so the refusal is here, where the buyer
+     * can be told something true and specific.
+     */
+    if (!sharedQuote.isShared &&
+        countDestinations(group.map(({ item }) => item)) > 1) {
+        throw new ValidationError("This seller ships one order to one address. Remove the extra delivery addresses, " +
+            "or order the items separately.");
+    }
     // The platform commission is now charged on EVERY payment method. It used to
     // be added only on the online-payment path, so COD / UPI-manual / cash / EMI
     // buyers silently never paid it.
@@ -848,7 +1020,7 @@ async function createOrderForGroup(group, orderType, ctx) {
      * compounds nine half-paisa errors instead of one, which is how a total
      * drifts from the sum of the lines shown beside it.
      */
-    roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0));
+    roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0) + sharedQuote.total);
     /*
      * ── D43: the COD deposit/remaining split, on the ORDER TOTAL ──────────────
      *
@@ -901,6 +1073,44 @@ async function createOrderForGroup(group, orderType, ctx) {
     const displayedUpiId = hasPaymentWindow
         ? await resolveDisplayedUpiId(firstItem.storeId, siteContactUpiVpa)
         : undefined;
+    /*
+     * ── POINTS TENDER (D46/D47) — a STAGE, after `orderTotal` is rounded ──────
+     *
+     * The deleted code redeemed points AFTER the orders existed and after the
+     * gateway had captured `orderTotal`, so a successful redemption took points
+     * from a buyer who had just paid full price — while its own comment claimed
+     * "the balance intact". This is the same feature done as a pipeline stage:
+     * `amountDue` is derived here, and `amountDue` is what the gateway captures
+     * and what the post-capture guard compares.
+     *
+     * 🛑 `useAllPoints` is the only client input and it is a BOOLEAN (decision
+     * 24). The amount comes from the live balance and the 50% cap; a
+     * client-supplied money figure is a client-supplied discount.
+     *
+     * 🛑 Per group, because the ACCEPTING store absorbs the redemption against
+     * its own payout (decision 3). A cart spanning an accepting and a
+     * non-accepting store must not pool the discount — so this reads
+     * `acceptsPoints`, which `resolveShippingCost` resolved from the store
+     * document it had already fetched.
+     *
+     * 🛑 `pointsBudget` is a SHARED MUTABLE REMAINDER, read once per checkout by
+     * the caller and decremented here — the same shape as
+     * `couponUsageAccumulator` and `platformFeeByStore`. Reading the balance
+     * per group would let two groups each spend the whole balance: `redeem`
+     * would then refuse the second one inside its transaction, leaving an order
+     * recorded at a discount that was never funded. One budget, drawn down in
+     * order, is what makes the sum of the groups equal what the buyer has.
+     */
+    const pointsOptedIn = useAllPoints === true;
+    const pointsAccepted = pointsOptedIn && acceptsPoints;
+    const { pointsApplied, amountDue } = resolvePointsTender({
+        orderTotal,
+        balance: pointsAccepted ? pointsBudget.remaining : 0,
+        accepted: pointsAccepted,
+        optedIn: pointsOptedIn,
+    });
+    if (pointsApplied > 0)
+        pointsBudget.remaining -= pointsApplied;
     // Both creation paths call the SAME builder — two hand-written copies is the
     // create-vs-create axis of Root Cause #39, and these two functions have
     // already drifted once before (add-on fees, Root Cause #65).
@@ -914,6 +1124,23 @@ async function createOrderForGroup(group, orderType, ctx) {
         quantity: totalQuantity,
         unitPrice: unitPriceFor(firstItem, firstProduct),
         totalPrice: orderTotal,
+        /*
+         * D46/D47 — what the points paid for, and what is left to collect.
+         *
+         * 🛑 `totalPrice` stays the FULL order value and is not reduced. It is the
+         * value of the supply, it is what the GST breakdown above was computed on,
+         * and it is what `refundableBase` measures against — netting the points
+         * off it would silently shrink the refundable base and the taxable value
+         * at once. Points are a DISCOUNT settled against goods (decision 5), so
+         * they reduce the amount COLLECTED, not the amount supplied.
+         *
+         * 🛑 Both are written only when non-zero, so an order placed without
+         * points carries neither field and every reader's `amountDue ?? totalPrice`
+         * fallback resolves to the right number on the 100% of historical orders
+         * that predate this.
+         */
+        pointsApplied: pointsApplied > 0 ? pointsApplied : undefined,
+        amountDue: pointsApplied > 0 ? amountDue : undefined,
         currency: firstItem.currency ?? getDefaultCurrency(),
         storeId: firstItem.storeId || undefined,
         storeName: firstItem.storeName || undefined,
@@ -971,11 +1198,34 @@ async function createOrderForGroup(group, orderType, ctx) {
         shipmentProtectionFee: !adminBypass && shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
         saleProtectionAddon: !adminBypass && saleProtectionFee > 0 ? true : undefined,
         saleProtectionFee: !adminBypass && saleProtectionFee > 0 ? saleProtectionFee : undefined,
+        /*
+         * S5a — the arrangement, snapshotted. Written only when it IS a shared
+         * purchase, so an ordinary order carries no field at all and every reader
+         * can test presence rather than compare a count to 1.
+         *
+         * 🛑 The FEES AS CHARGED, not the store's current rates. That is the whole
+         * point of a snapshot: an order refunded in six months must reverse what
+         * was collected, not what the seller charges by then.
+         */
+        sharedPurchase: sharedQuote.isShared
+            ? {
+                destinationCount: countDestinations(group.map(({ item }) => item)),
+                handlingFee: sharedQuote.handlingFee,
+                extraShippingFee: sharedQuote.extraShippingFee,
+            }
+            : undefined,
         taxableAmount: gstBreakdown?.taxableAmount,
         /* Exempt goods are a reportable nil-rated supply, kept OUT of
          * `taxableAmount` so the taxed base stays the base the tax was charged on,
          * and recorded here so the invoice's columns can reconcile. */
         exemptAmount: gstBreakdown?.exemptAmount || undefined,
+        /*
+         * Phase 7 — the place of supply, which is the INPUT the CGST/SGST-vs-IGST
+         * split above was computed from. Only the split's RESULT was recorded
+         * before, so an order could not state why it was taxed the way it was, and
+         * GSTR-1's mandatory place-of-supply column had nothing to read.
+         */
+        placeOfSupply: buyerState || undefined,
         /* The supplier of record AS IT STANDS NOW. A tax invoice without the
          * supplier's GSTIN is not a tax invoice, and the invoice page cannot read
          * it from site settings — `gst` is in PRIVATE_SITE_FIELDS. See the schema.
@@ -1039,6 +1289,9 @@ async function createOrderForGroup(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // The second half of the points tender — see `settlePointsTender`. Runs
+    // before the caller asks the gateway for anything.
+    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
     // Close the loop on any locked line this order settled: flip the offer to
     // "paid" (its terminal status had NO server-side writer before 2026-08-21,
     // so an accepted offer could be re-added and re-ordered) and back-link the
@@ -1388,6 +1641,24 @@ export async function createCheckoutOrderAction(input) {
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, commissions));
+    /*
+     * ── The checkout's points budget, read ONCE (D46/D47) ─────────────────────
+     *
+     * 🛑 One read for the whole checkout, not one per order group. Rule #6
+     * budgets ~3 sequential Firestore round-trips per request, and a cart
+     * spanning four sellers would otherwise pay four reads to learn one number.
+     *
+     * 🛑 And ZERO when the buyer did not opt in, so an ordinary checkout performs
+     * no points read at all — the common case must not pay for a feature it is
+     * not using.
+     *
+     * 🛑 `adminBypass` is deliberately excluded: that path takes no payment, so
+     * there is nothing for points to reduce, and debiting a buyer's balance for
+     * an order the admin placed free would be a theft with an audit-log entry
+     * saying otherwise.
+     */
+    const useAllPoints = cart.useAllPoints === true && !adminBypass;
+    const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
     const groupCtx = {
         paymentMethod,
         emiTenureMonths,
@@ -1415,6 +1686,8 @@ export async function createCheckoutOrderAction(input) {
         platformFeeByStore,
         selectedShippingQuote: input.selectedShippingQuote,
         productById: checkoutProductById,
+        useAllPoints,
+        pointsBudget,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
@@ -1448,18 +1721,26 @@ export async function createCheckoutOrderAction(input) {
      * Deleting it leaves a promise with no mechanism, which is a disappointment.
      * Keeping it left a mechanism that silently takes points, which is a theft.
      *
-     * ## What the real tender has to do instead
-     *
-     * Points are a TENDER, so they belong in the pricing pipeline, not after it:
-     * a stage in `computeCheckoutTotal` AFTER rounding — `amountDue = total −
-     * pointsApplied` — with the gateway capturing `amountDue` and the
-     * post-capture guard comparing against `amountDue`. Anything else makes
-     * points a sixth way the captured amount can diverge from the recorded order
-     * total, which is the D37/D38/D40 family this plan exists to close.
-     *
-     * Everything that work needs now exists: `purchase_earn`, per-batch expiry,
-     * FIFO consumption, `redemption_reversal` and the seller-funded deduction.
-     * What is missing is the pipeline stage and the two document fields.
+     * ## ✅ The real tender was BUILT 2026-10-22 — and it is not here
+     *
+     * 🛑 Do not look for it at this line. Points are a TENDER, so they are a
+     * STAGE inside each order-creation path, immediately after that path's single
+     * `roundRupees` and BEFORE anything is written or captured:
+     *
+     *   - `resolvePointsTender` (`_internal/shared/checkout/order-math.ts`) —
+     *     the arithmetic, beside every other money rule.
+     *   - the stage in `createOrderForGroup` and `createPhonePeGroupOrder`,
+     *     which write `pointsApplied` + `amountDue` onto the order.
+     *   - `settlePointsTender` — ONE debit implementation shared by both paths,
+     *     running after the order exists so the discount and the debit are two
+     *     halves of one recorded fact, and reverting the discount if `redeem`
+     *     refuses.
+     *
+     * This note stays because the mistake is worth keeping, but a comment saying
+     * a feature is "missing" while it sits 800 lines above is its own trap — it
+     * is how `assertReturnWindowOpen` got reported as absent when my own comment
+     * was shadowing the real answer. The accurate statement is: the tender is
+     * built, and this is the wrong place for it.
      */
     dispatchOrderConfirmationEmails(emailsToSend);
     serverLogger.info(`createCheckoutOrderAction: ${orderIds.length} order(s) placed for uid=${uid}` +
@@ -1493,7 +1774,11 @@ const EMPTY_PRICING_PREVIEW = {
     couponDiscount: 0,
     platformFee: 0,
     gstOnFee: 0,
+    sharedPurchaseFee: 0,
     total: 0,
+    pointsApplied: 0,
+    amountDue: 0,
+    pointsBalance: 0,
     stores: [],
 };
 /**
@@ -1566,7 +1851,7 @@ export async function previewCheckoutPricing(input) {
          * and then the order path (equally unpassed) charged it. Preview and charge
          * agreed, and both were wrong in the same direction.
          */
-        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled, acceptsPoints, sharedPurchaseRates: previewSharedRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
         const addons = cart.storeAddons?.[firstItem.storeId] ?? {};
@@ -1617,6 +1902,28 @@ export async function previewCheckoutPricing(input) {
          * seller cannot flip the switch after the sale).
          */
         const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+        /*
+         * ── S5a in the PREVIEW ───────────────────────────────────────────────────
+         *
+         * 🛑 Here because a coordinator commits against this figure. The plan is
+         * explicit that the fees "must be shown before the coordinator commits" —
+         * a handling fee plus N−1 shipping legs discovered afterwards is exactly
+         * the surprise the arrangement makes expensive.
+         *
+         * The same function and the same `countDestinations` as both order paths,
+         * so the shown figure and the charged one cannot diverge. D37 is the record
+         * of what ONE money term reaching three of four paths costs: the buyer was
+         * shown one number, charged another, and the order recorded the first.
+         *
+         * 🛑 A preview NEVER throws, so an unpriced arrangement contributes 0 here
+         * rather than raising — `quoteSharedPurchase` reports it on `unpriced` and
+         * the ORDER path is what refuses. A preview that threw would render the
+         * whole cart as an error page for a seller's missing config.
+         */
+        const groupSharedPurchaseFee = quoteSharedPurchase({
+            destinationCount: countDestinations(group.map(({ item }) => item)),
+            rates: previewSharedRates,
+        }).total;
         const { shippingProtectionFee: groupShipmentProtectionFee, saleProtectionFee: groupSaleProtectionFee, } = computeProtectionFees({
             subtotal: groupTotal,
             selected: {
@@ -1701,10 +2008,19 @@ export async function previewCheckoutPricing(input) {
                 groupEmiSurcharge +
                 groupGiftWrapFee +
                 groupShipmentProtectionFee +
-                groupSaleProtectionFee,
+                groupSaleProtectionFee +
+                // S5a — a term in the per-store total, so the seller card and the
+                // order it previews agree.
+                groupSharedPurchaseFee,
             supportsShippingProtection: storeProtections.shipping,
             supportsSaleProtection: storeProtections.sale,
             hasFinalSaleItem: groupHasFinalSale,
+            acceptsPoints,
+            sharedPurchaseFee: groupSharedPurchaseFee,
+            // Filled by the tender pass below — it needs each store's share of the
+            // one capped commission, which is only allocatable once every group is
+            // known.
+            pointsApplied: 0,
         });
     }
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
@@ -1714,11 +2030,21 @@ export async function previewCheckoutPricing(input) {
     const giftWrapFeeTotal = sum((s) => s.giftWrapFee);
     const shipmentProtectionFeeTotal = sum((s) => s.shipmentProtectionFee);
     const saleProtectionFeeTotal = sum((s) => s.saleProtectionFee);
+    // S5a — summed from the same per-store figures, so the aggregate cannot
+    // disagree with the seller cards it is built from.
+    const sharedPurchaseFeeTotal = sum((s) => s.sharedPurchaseFee);
     const gstAmount = sum((s) => s.gstAmount);
     const couponDiscount = sum((s) => s.couponDiscount);
     // One capped commission for the whole checkout, on every payment method —
     // deliberately not per store, so it is not added to the per-store rows above.
-    const { platformFee, gstOnFee } = computeCheckoutFees(cartSubtotal, commissions);
+    // The whole object is kept (not just the two fields) because the points
+    // tender below re-allocates it per store through `allocateCheckoutFees`,
+    // which takes a `CheckoutFees` — and `totalFee` carries the
+    // `minimumTransactionFee` floor, which is exactly the field D41 found had no
+    // consumer anywhere. Destructuring it away here would be how it loses its
+    // second one.
+    const checkoutFees = computeCheckoutFees(cartSubtotal, commissions);
+    const { platformFee, gstOnFee } = checkoutFees;
     /*
      * 🛑 `gstAmount` is NOT a term, and leaving it in was a shown-vs-charged
      * drift waiting on a settings flag.
@@ -1751,8 +2077,52 @@ export async function previewCheckoutPricing(input) {
         giftWrapFeeTotal +
         shipmentProtectionFeeTotal +
         saleProtectionFeeTotal +
+        // S5a — a real additive charge, so it belongs in the column with the other
+        // fees rather than below the total like the tax-inclusive `gstAmount`.
+        sharedPurchaseFeeTotal +
         platformFee +
         gstOnFee;
+    /*
+     * ── THE POINTS TENDER, PREVIEWED (D46/D47) ────────────────────────────────
+     *
+     * 🛑 Applied PER STORE against the SAME base the order path uses, which is
+     * why this runs here and not inside the loop above: the base includes each
+     * store's share of the one capped commission, and that share is only
+     * allocatable once every group is known.
+     *
+     * 🛑 Per store is not a detail — it is the only shape that can agree with
+     * what gets charged. A cart-level application gives the same answer as the
+     * per-group one whenever every store accepts (the sum of per-group 50% caps
+     * equals 50% of the sum), and a DIFFERENT answer the moment one store does
+     * not: with ₹500 at an accepting store, ₹500 at a declining one and a 600
+     * balance, per-store applies ₹250 and cart-level would promise ₹500. The
+     * buyer would be shown a discount half of which could never be honoured.
+     *
+     * The iteration order matches `orderGroups`, and so does the order-creation
+     * loop, so the budget is drawn down in the same sequence in both — which is
+     * what makes the two sums identical rather than merely close.
+     */
+    const previewUseAllPoints = cart.useAllPoints === true;
+    const previewBalance = previewUseAllPoints ? await safePointsBalance(uid) : 0;
+    if (previewUseAllPoints && previewBalance > 0) {
+        const feeByStore = allocateCheckoutFees(stores.map((s) => [s.storeId, s.subtotal]), checkoutFees);
+        const { perGroup } = allocatePointsAcrossGroups(stores.map((s) => {
+            const share = feeByStore.get(s.storeId);
+            return {
+                // The SAME base `createOrderForGroup` applies the tender to: the
+                // store's charged total plus its share of the one capped commission.
+                // `store.total` deliberately excludes that share (it is a checkout
+                // charge, not a per-store one), so it is added back here rather than
+                // by widening a published field.
+                total: roundRupees(s.total + (share?.platformFee ?? 0) + (share?.gstOnFee ?? 0)),
+                accepted: s.acceptsPoints,
+            };
+        }), previewBalance, true);
+        perGroup.forEach((applied, i) => {
+            stores[i].pointsApplied = applied;
+        });
+    }
+    const pointsApplied = sum((s) => s.pointsApplied);
     return {
         subtotal: cartSubtotal,
         shippingFee,
@@ -1761,11 +2131,17 @@ export async function previewCheckoutPricing(input) {
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,
+        sharedPurchaseFee: sharedPurchaseFeeTotal,
         gstAmount,
         couponDiscount,
         platformFee,
         gstOnFee,
         total,
+        pointsApplied,
+        // Equal to `total` when no points apply, so every existing reader of
+        // either figure keeps getting the right number.
+        amountDue: roundRupees(total - pointsApplied),
+        pointsBalance: previewBalance,
         stores,
     };
 }
@@ -1916,7 +2292,7 @@ async function refundDroppedItemsForPhonePeCheckout(input) {
  * from the inline version this replaced.
  */
 async function createPhonePeGroupOrder(group, orderType, ctx) {
-    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, } = ctx;
+    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, useAllPoints, pointsBudget, } = ctx;
     /*
      * Which online gateway actually took the money, read off the registered
      * provider rather than passed in — exactly one is registered per process
@@ -1932,7 +2308,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     // seller group here, duplicated from resolveShippingCost.
     // D44: `groupTotal` is computed just above — pass it so a free-above
     // threshold can fire and an unpriceable store is recorded.
-    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections, acceptsPoints, sharedPurchaseRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
     /*
      * Same supplier-of-record rule as `createOrderForGroup`, through the same
      * function. This path (PhonePe verify / webhook) is the SECOND place an
@@ -2050,9 +2426,51 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     /* Product GST is not a term — prices are tax-inclusive, so it is already
      * inside `groupTotal`. Matches the COD/UPI path exactly; `platformFeeGst`
      * stays because that is GST on our fee, charged on top. */
+    /*
+     * ── S5a: the shared-purchase arrangement, matching the COD/manual path ────
+     *
+     * Same function, same inputs, same position — before `orderTotal`, because
+     * it is a term in it. See the fuller 🛑 at the COD/manual site for why the
+     * rates are snapshotted and why an unpriced arrangement is refused rather
+     * than quoted at ₹0.
+     *
+     * 🛑 On THIS path the money is already captured by the time this runs, so a
+     * refusal here means a charged-with-no-order — the D64 class. That is why
+     * `/api/payment/create-order` must apply the same term: the pre-payment
+     * amount and this total have to agree, which is the parity C0c defect 1 was
+     * about and the reason every addition here has to be made in three places.
+     */
+    const phonepeSharedQuote = quoteSharedPurchase({
+        destinationCount: countDestinations(group.map(({ item }) => item)),
+        rates: sharedPurchaseRates,
+    });
     // D42: rounded once on the sum — see the COD/UPI path's 🛑 for why a raw
     // float sum of seven 2dp terms reached Firestore as 1011.8000000000001.
-    const orderTotal = roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst);
+    const orderTotal = roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + phonepeSharedQuote.total);
+    /*
+     * ── POINTS TENDER (D46/D47) — the same STAGE as the COD/manual path ───────
+     *
+     * Same four inputs, same function, same point in the sequence: immediately
+     * after `orderTotal`'s single `roundRupees` and before anything is written.
+     * Computing it here rather than in a shared builder is unavoidable — the two
+     * paths derive `orderTotal` separately — but the ARITHMETIC is
+     * `resolvePointsTender` in both, so they cannot disagree about the amount
+     * the way the add-on fees once did (Root Cause #65).
+     *
+     * 🛑 This is the path whose capture matters most: `amountDue` is what the
+     * Razorpay order is created for, so a divergence here is money taken that
+     * the order does not record.
+     */
+    const pointsOptedIn = useAllPoints === true;
+    const pointsAccepted = pointsOptedIn && acceptsPoints;
+    const { pointsApplied, amountDue } = resolvePointsTender({
+        orderTotal,
+        balance: pointsAccepted ? pointsBudget.remaining : 0,
+        accepted: pointsAccepted,
+        optedIn: pointsOptedIn,
+    });
+    if (pointsApplied > 0)
+        pointsBudget.remaining -= pointsApplied;
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
     // the price rule (`isBundle ? item.price : product.price`) that — like the
@@ -2089,6 +2507,10 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         quantity: totalQuantity,
         unitPrice: group[0].product.price,
         totalPrice: orderTotal,
+        // D46/D47 — see the identical pair in `createOrderForGroup`. `totalPrice`
+        // stays the full value of the supply; points reduce what is COLLECTED.
+        pointsApplied: pointsApplied > 0 ? pointsApplied : undefined,
+        amountDue: pointsApplied > 0 ? amountDue : undefined,
         currency: firstItem.currency ?? getDefaultCurrency(),
         storeId: firstItem.storeId || undefined,
         storeName: firstItem.storeName || undefined,
@@ -2120,7 +2542,15 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         paymentRecord: {
             method: gatewayName === "razorpay" ? "razorpay" : "phonepe",
             transactionId: transactionId ?? merchantOrderId,
-            amount: orderTotal,
+            /*
+             * 🛑 What the gateway actually CAPTURED, which is `amountDue` once points
+             * are applied — not the order's value. This record is the evidence a
+             * reconciler compares against the gateway's own figure (Phase 4 R2), so
+             * writing `orderTotal` here would open an `amount_mismatch` case on every
+             * points-funded order: the discount would read as money we failed to
+             * collect.
+             */
+            amount: amountDue,
             paidAt: new Date(),
             verifiedBy: `${gatewayName}-order-status`,
             verificationMethod: "order-status",
@@ -2148,6 +2578,14 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         // Recorded as well as charged — an order that collects a protection fee
         // without a record of it cannot be reconciled against a later claim.
         saleProtectionFee: saleProtectionFee > 0 ? saleProtectionFee : undefined,
+        // S5a — snapshotted, matching the COD/manual path field for field.
+        sharedPurchase: phonepeSharedQuote.isShared
+            ? {
+                destinationCount: countDestinations(group.map(({ item }) => item)),
+                handlingFee: phonepeSharedQuote.handlingFee,
+                extraShippingFee: phonepeSharedQuote.extraShippingFee,
+            }
+            : undefined,
         /*
          * The tax breakdown, matching `createOrderForGroup` field for field.
          * This path recorded NONE of it before C0c defect 1 — so an online order
@@ -2158,6 +2596,10 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
          */
         taxableAmount: phonepeGst?.taxableAmount,
         exemptAmount: phonepeGst?.exemptAmount || undefined,
+        // Phase 7 — the place of supply, matching `createOrderForGroup` field for
+        // field. This path recorded NONE of the tax breakdown until C0c defect 1,
+        // which is precisely why every addition here has to be made twice.
+        placeOfSupply: buyerState || undefined,
         // Our registration at the moment of supply — see the schema. Mirrors the
         // COD/UPI path so both produce an invoiceable order.
         supplierGstin: supplier.gstin,
@@ -2177,6 +2619,9 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // The second half of the points tender — one implementation, shared with the
+    // COD/manual path. See `settlePointsTender`.
+    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
     // Close the loop on any locked line this order settled: flip the offer to
     // "paid" (its terminal status had NO server-side writer before 2026-08-21,
     // so an accepted offer could be re-added and re-ordered) and back-link the
@@ -2538,7 +2983,12 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         // percentages, so the moment the cap landed it would have expected more
         // than was actually collected and rejected every legitimate payment.
         const commissionRates = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
-        const { platformFee: expectedPlatformFee, gstOnFee: expectedGstOnFee } = computeCheckoutFees(cartSubtotalRs, commissionRates);
+        // The whole object is kept so the points tender below can re-allocate it
+        // per group — see the same note in `previewCheckoutPricing`. `totalFee`
+        // carries the `minimumTransactionFee` floor, and destructuring it away is
+        // how it lost every consumer once already (D41).
+        const expectedFees = computeCheckoutFees(cartSubtotalRs, commissionRates);
+        const { platformFee: expectedPlatformFee, gstOnFee: expectedGstOnFee } = expectedFees;
         // Same per-seller-group shipping sum /api/payment/create-order charged
         // upfront (and the same resolveShippingCost createPhonePeGroupOrder
         // below will use to build each order's recorded totalPrice) — keeps this
@@ -2624,11 +3074,62 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
          * would make this guard demand ~₹580 more than the buyer owes on a
          * ₹5,547 cart — rejecting every correctly-charged order.
          */
-        const expectedPaymentAmountRs = expectedDiscountedSubtotal +
+        /*
+         * ── D46/D47 — the guard must expect the amount NET OF POINTS ─────────────
+         *
+         * 🛑 Omitting this term would make the guard reject every correctly-charged
+         * points order, which is worse than the overcharge it exists to catch: the
+         * money is already captured by the time this runs, so a false rejection is
+         * a charged-with-no-order — the D64 class.
+         *
+         * The bases are rebuilt here from the same terms in the same order, and the
+         * draw-down is the same shared allocator, so the only way this can diverge
+         * from the capture route is a change made to one and not the other. That is
+         * precisely the drift the four-way export comment on
+         * `allocatePointsAcrossGroups` exists to make visible.
+         */
+        const guardUseAllPoints = cart.useAllPoints === true;
+        let expectedPointsApplied = 0;
+        if (guardUseAllPoints) {
+            const guardBalance = await safePointsBalance(uid);
+            if (guardBalance > 0) {
+                const guardSubtotals = expectedShippingGroups.map((g) => [
+                    g.items[0].item.storeId,
+                    g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0),
+                ]);
+                const guardFeeByGroup = allocateCheckoutFees(guardSubtotals, expectedFees);
+                const guardCouponByGroup = computeCartCouponDiscount(cart.appliedCoupons ?? [], expectedShippingGroups.map((g) => ({
+                    storeId: g.items[0].item.storeId,
+                    lines: g.items.map(({ item, product }) => ({
+                        itemId: item.itemId,
+                        lineTotal: lineTotalFor(item, product),
+                    })),
+                }))).perGroup;
+                const guardBases = expectedShippingGroups.map((g, i) => {
+                    const storeId = g.items[0].item.storeId;
+                    const addons = cart.storeAddons?.[storeId] ?? {};
+                    const goods = guardSubtotals[i][1];
+                    const share = guardFeeByGroup.get(storeId);
+                    const groupAddons = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
+                        computeShipmentProtectionFee(goods, addons.shipmentProtectionAddon ?? false, commissionRates);
+                    return {
+                        total: roundRupees(Math.max(0, goods - (guardCouponByGroup[i]?.couponDiscount ?? 0)) +
+                            (expectedShippingFees[i]?.shippingFee ?? 0) +
+                            groupAddons +
+                            (share?.platformFee ?? 0) +
+                            (share?.gstOnFee ?? 0)),
+                        accepted: expectedShippingFees[i]?.acceptsPoints === true,
+                    };
+                });
+                expectedPointsApplied = allocatePointsAcrossGroups(guardBases, guardBalance, true).pointsApplied;
+            }
+        }
+        const expectedPaymentAmountRs = roundRupees(Math.max(0, expectedDiscountedSubtotal +
             expectedPlatformFee +
             expectedGstOnFee +
             expectedAddonFees +
-            expectedShippingFee;
+            expectedShippingFee -
+            expectedPointsApplied));
         // Reuses the order already fetched above to confirm COMPLETED — PhonePe's
         // own amount is in its wire-format smallest unit. // audit-money-units-ok: describes the PhonePe boundary conversion this line performs, not our storage convention
         const paidAmountRs = paiseToRupees(gatewayOrder.amount);
@@ -2703,6 +3204,19 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
+    /*
+     * The points budget for this checkout — one read, zero when not opted in.
+     * See the identical pair in the COD/manual path for why it is a shared
+     * remainder rather than a per-group balance read.
+     *
+     * 🛑 On THIS path the money has already been captured by the time these
+     * orders are created, so the budget must match whatever the pre-payment
+     * amount was computed against. That is why `useAllPoints` is read off the
+     * cart here too and not re-decided: the figure quoted to the gateway and the
+     * figure recorded on the orders come from the same cart flag.
+     */
+    const useAllPoints = cart.useAllPoints === true;
+    const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
     for (const { items: group, orderType } of orderGroups) {
         total += await createPhonePeGroupOrder(group, orderType, {
             appliedCoupons,
@@ -2728,6 +3242,8 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             emailsToSend,
             couponUsageAccumulator,
             productById: productByIdPaid,
+            useAllPoints,
+            pointsBudget,
         });
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);