@mohasinac/appkit 4.55.0 → 4.57.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.55.0",
-  "head": "e683e7b08996d66d9b6bef65cf4712b8e63454ea",
+  "version": "4.57.0",
+  "head": "de32aea7a1bbb5fe9970959866c5278c2f9e4e49",
   "branch": "main",
-  "dirty": false,
-  "builtAt": "2026-10-20T15:42:52.181Z"
+  "dirty": true,
+  "builtAt": "2026-10-20T18:02:32.256Z"
 }

package/dist/_internal/server/features/checkout/actions.d.ts

@@ -1,3 +1,4 @@
+import { type SelectedShippingQuote } from "../../../shared/shipping/quote";
 import { type StoreShippingPolicy } from "../../../shared/features/shipping/mode";
 import { type CartLane } from "../../../shared/checkout/lanes";
 import type { OutOfStockPolicy } from "../../../../features/orders/schemas/index";
@@ -12,6 +13,36 @@ export interface CreateCheckoutOrderInput {
     paymentMethod: CheckoutPaymentMethod;
     /** Required when paymentMethod === "emi" — the buyer's chosen tenure (2–6 months). */
     emiTenureMonths?: number;
+    /**
+     * The courier the buyer picked at checkout, with the ₹50-rounded rate they
+     * were shown.
+     *
+     * 🛑 OPTIONAL, and its absence is meaningful: a cart whose carrier quote
+     * failed, a digital-only cart, or any caller written before the picker
+     * existed falls back to `resolveShippingCost` exactly as before. Absence is
+     * what makes reconciliation skip the order as "no-quote" rather than
+     * measuring a seller's spend against a figure nobody was charged.
+     *
+     * 🛑 `chargedRate` is TRUSTED from the client, and that is a deliberate,
+     * bounded decision rather than an oversight. It is re-derived server-side
+     * through `roundShippingUp` before it is billed, so a tampered value can
+     * only ever be a different carrier rate rounded the same way — the gap
+     * worth closing is re-quoting the carrier at order time, which costs an
+     * outbound call on the payment path and is tracked separately.
+     */
+    selectedShippingQuote?: SelectedShippingQuote;
+    /**
+     * Points the buyer chose to spend on this checkout. 1 point = ₹1.
+     *
+     * 🛑 Requested, never trusted. The server re-reads the balance, re-applies
+     * the 50% cap against the real cart total, and spends the LESSER of the two
+     * — a client that asks for more than it holds gets its request trimmed, not
+     * an error, because the honest reading of "spend 500 when you have 300" is a
+     * stale page rather than an attack. `pointsRepository.redeem` then re-checks
+     * the balance a third time inside its own transaction, which is the check
+     * that actually prevents a negative balance under concurrency.
+     */
+    pointsToRedeem?: number;
     notes?: string;
     excludedProductIds?: string[];
     /** When true this is an admin test order — OTP consent is pre-granted and the order is created paid/processing. */
@@ -105,6 +136,18 @@ export interface CheckoutPricingPreviewInput {
      * is currently gated off.
      */
     lane?: CartLane;
+    /**
+     * The chosen EMI tenure, when `paymentMethod` is `"emi"`.
+     *
+     * 🛑 REQUIRED for an EMI preview to be truthful. The surcharge is
+     * `principalRemaining × surchargePercentPerMonth × tenureMonths`, so it
+     * cannot be derived from the cart alone — and without it this function
+     * returned a total that `createOrderForGroup` then exceeded by exactly that
+     * amount. Unlike the add-ons below, the tenure is NOT on the cart document:
+     * it is picked on the payment step and belongs to the order, so it has to
+     * travel with the request.
+     */
+    emiTenureMonths?: number;
 }
 /** One store's slice of the preview — what that seller's order will cost. */
 export interface CheckoutPricingPreviewStore {
@@ -116,6 +159,14 @@ export interface CheckoutPricingPreviewStore {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /**
+     * EMI surcharge for THIS seller, when the buyer is previewing an EMI order.
+     *
+     * Per store because `computeEmiSchedule` takes a SELLER subtotal — the
+     * financed principal is per order, not per cart, so a cart-wide figure
+     * would not match any order written.
+     */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     total: number;
@@ -147,6 +198,8 @@ export interface CheckoutPricingPreview {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /** Total EMI surcharge across sellers. Zero unless previewing an EMI order. */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     /** Buyer-facing platform commission, capped, charged once for this checkout. */

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

@@ -12,6 +12,9 @@ import { roundRupees } from "../../../../utils/number.formatter.js";
 import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../../../errors/index.js";
 import { ORDER_FIELDS } from "../../../../constants/field-names.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { roundShippingUp, } from "../../../shared/shipping/quote.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { maxRedeemablePoints } from "../../../../features/points/schemas/firestore.js";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
 import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
@@ -44,7 +47,7 @@ import { verifyPaymentSignature as verifyRazorpayPaymentSignature } from "../../
 import { resolveKeys } from "../../../../core/integration-keys.js";
 import { paiseToRupees } from "../../../../core/money.js";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config.js";
-import { checkEmiEligibility, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
+import { checkEmiEligibility, computeBuyerEmiQuote, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
 import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, } from "../../../shared/checkout/rules/index.js";
@@ -490,7 +493,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, } = 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 firstItem = group[0].item;
     const firstProduct = group[0].product;
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
@@ -507,7 +510,25 @@ async function createOrderForGroup(group, orderType, ctx) {
         return expandCartLineToOrderRows(item, product, ctx.productById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
-    const { shippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    /*
+     * 🛑 The buyer's quote WINS over the seller's configured rate, and it is
+     * re-rounded here rather than trusted as sent.
+     *
+     * `roundShippingUp` is idempotent, so re-applying it to an honest value is a
+     * no-op; applied to a tampered one it forces the result back onto a ₹50 step.
+     * That bounds what a forged `chargedRate` can be to "some carrier rate,
+     * correctly rounded" rather than an arbitrary number.
+     *
+     * Applied to the FIRST group only — see the field's note on OrderGroupContext.
+     * A cart spanning sellers must not be charged the same parcel rate twice.
+     */
+    const isFirstGroup = ctx.orderIds.length === 0;
+    const shippingFee = selectedShippingQuote && isFirstGroup
+        ? roundShippingUp(selectedShippingQuote.chargedRate)
+        : selectedShippingQuote
+            ? 0
+            : resolvedShippingFee;
     /*
      * Who issues this invoice — the seller if they have their own GSTIN, the
      * platform otherwise. ONE function decides, and it is the only place that
@@ -678,6 +699,16 @@ async function createOrderForGroup(group, orderType, ctx) {
         // are "auction". Written ONCE here and never recomputed: the auction and
         // offer documents it summarises are mutable and eventually archived.
         sourceContext,
+        /*
+         * Frozen onto the order so reconciliation has a charged figure to measure
+         * the seller's real postage against. Only on the group that actually
+         * carries the shipping fee — a later group in a multi-seller cart is
+         * charged ₹0 shipping, so recording a quote there would invite a credit
+         * against money that group never collected.
+         */
+        selectedShippingQuote: selectedShippingQuote && isFirstGroup
+            ? { ...selectedShippingQuote, chargedRate: shippingFee }
+            : undefined,
         offerId: firstItem.offerId ?? undefined,
         // Distinguishes a Buy Now purchase from a settled auction win. Both are
         // orderType "auction"; only this one gets the 24h admin-review window.
@@ -1139,12 +1170,53 @@ export async function createCheckoutOrderAction(input) {
         siteContactUpiVpa: siteSettings?.contact?.upiVpa,
         storeAddons: cart.storeAddons,
         platformFeeByStore,
+        selectedShippingQuote: input.selectedShippingQuote,
         productById: checkoutProductById,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);
+    /*
+     * Spend points AFTER the orders exist.
+     *
+     * 🛑 This ordering is the whole safety argument. Redeeming first and then
+     * failing to create an order would debit a buyer for something they never
+     * received, and points have no refund path that does not need a human. This
+     * way the worst case is an order placed at full price with the balance
+     * intact — recoverable, and visible to the buyer, who still has their
+     * points.
+     *
+     * The amount is re-derived server-side against the real total rather than
+     * taken from the request; `maxRedeemablePoints` applies the 50% cap, and
+     * `redeem` re-checks the balance inside its own transaction.
+     */
+    if (input.pointsToRedeem && input.pointsToRedeem > 0 && orderIds.length > 0) {
+        try {
+            const balance = await pointsRepository.getBalance(uid);
+            const spend = maxRedeemablePoints(total, Math.min(balance, input.pointsToRedeem));
+            if (spend > 0) {
+                await pointsRepository.redeem({
+                    userId: uid,
+                    points: spend,
+                    orderId: orderIds[0],
+                    description: `Redeemed on ${orderIds[0]}`,
+                });
+            }
+        }
+        catch (err) {
+            /*
+             * A failed redemption must not fail a placed order. The buyer keeps the
+             * points and paid full price — the strictly safer side of this trade.
+             */
+            const normalized = normalizeError(err);
+            serverLogger.error("points redemption failed after order creation", {
+                uid,
+                orderId: orderIds[0],
+                message: normalized.message,
+            });
+        }
+    }
     dispatchOrderConfirmationEmails(emailsToSend);
     serverLogger.info(`createCheckoutOrderAction: ${orderIds.length} order(s) placed for uid=${uid}` +
         (unavailable.length > 0 ? ` (${unavailable.length} item(s) unavailable)` : ""));
@@ -1172,6 +1244,7 @@ const EMPTY_PRICING_PREVIEW = {
     giftWrapFee: 0,
     shipmentProtectionFee: 0,
     saleProtectionFee: 0,
+    emiSurcharge: 0,
     gstAmount: 0,
     couponDiscount: 0,
     platformFee: 0,
@@ -1189,7 +1262,7 @@ const EMPTY_PRICING_PREVIEW = {
  * stock, creates an order, or writes coupon usage.
  */
 export async function previewCheckoutPricing(input) {
-    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, } = input;
+    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, emiTenureMonths, } = input;
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const cart = await unitOfWork.carts.getOrCreate(uid);
@@ -1242,7 +1315,7 @@ export async function previewCheckoutPricing(input) {
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
         const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-        const { shippingFee: groupShippingFee, storeState, storeProtections } = await resolveShippingCost(firstItem.storeId);
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId);
         // 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] ?? {};
@@ -1250,6 +1323,36 @@ export async function previewCheckoutPricing(input) {
         // ever charged for literal "cod" (pay the courier), never upi_manual or
         // cash (both pre-paid via UPI/bank transfer before dispatch).
         const groupCodHandlingFee = paymentMethod === "cod" ? computeCodHandlingFee(groupTotal, commissions) : 0;
+        /*
+         * 🛑 The EMI surcharge is a TERM OF THE TOTAL, and it was missing here
+         * while `createOrderForGroup` added it — a shown-vs-charged drift of
+         * exactly the kind this function exists to prevent.
+         *
+         * Measured on the live settings (tokenPercent 10, surchargePercentPerMonth
+         * 1) against the ₹20,000 listing: token ₹2,000, financed ₹18,000, so the
+         * surcharge is ₹360 at the default 2-month tenure and ₹1,080 at 6. The
+         * Order Summary showed ₹20,011.80 either way, and the order recorded up to
+         * ₹1,080 more. Worse, the EMI panel beside it already displayed
+         * instalments computed WITH the surcharge, so the page disagreed with
+         * itself.
+         *
+         * `computeBuyerEmiQuote`, never `computeEmiSchedule`: the latter also
+         * returns the platform/seller split of the surcharge, which is our
+         * commercial arrangement with the seller and has no business reaching a
+         * browser (see § "Buyer-facing fees").
+         *
+         * Eligibility is deliberately NOT enforced here. A preview that threw
+         * would blank the Order Summary; `createOrderForGroup` still refuses an
+         * ineligible EMI order, which is where refusing belongs. An ineligible
+         * cart simply previews no surcharge, because the tenure never applies.
+         */
+        let groupEmiSurcharge = 0;
+        if (paymentMethod === "emi" && emiTenureMonths && siteSettings?.emi) {
+            const emiSettings = siteSettings.emi;
+            if (checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings).eligible) {
+                groupEmiSurcharge = computeBuyerEmiQuote(groupTotal, emiTenureMonths, emiSettings).surchargeAmount;
+            }
+        }
         const groupGiftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissions);
         /*
          * C5e — the same three tiers `createOrderForGroup` enforces, so the figure
@@ -1302,6 +1405,7 @@ export async function previewCheckoutPricing(input) {
             subtotal: groupTotal,
             shippingFee: groupShippingFee,
             codHandlingFee: groupCodHandlingFee,
+            emiSurcharge: groupEmiSurcharge,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
             saleProtectionFee: groupSaleProtectionFee,
@@ -1319,6 +1423,7 @@ export async function previewCheckoutPricing(input) {
             total: Math.max(0, groupTotal - groupCouponDiscount) +
                 groupShippingFee +
                 groupCodHandlingFee +
+                groupEmiSurcharge +
                 groupGiftWrapFee +
                 groupShipmentProtectionFee +
                 groupSaleProtectionFee,
@@ -1330,6 +1435,7 @@ export async function previewCheckoutPricing(input) {
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
     const shippingFee = sum((s) => s.shippingFee);
     const codHandlingFee = sum((s) => s.codHandlingFee);
+    const emiSurcharge = sum((s) => s.emiSurcharge);
     const giftWrapFeeTotal = sum((s) => s.giftWrapFee);
     const shipmentProtectionFeeTotal = sum((s) => s.shipmentProtectionFee);
     const saleProtectionFeeTotal = sum((s) => s.saleProtectionFee);
@@ -1366,6 +1472,7 @@ export async function previewCheckoutPricing(input) {
     const total = Math.max(0, cartSubtotal - couponDiscount) +
         shippingFee +
         codHandlingFee +
+        emiSurcharge +
         giftWrapFeeTotal +
         shipmentProtectionFeeTotal +
         saleProtectionFeeTotal +
@@ -1375,6 +1482,7 @@ export async function previewCheckoutPricing(input) {
         subtotal: cartSubtotal,
         shippingFee,
         codHandlingFee,
+        emiSurcharge,
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,
@@ -1536,7 +1644,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     // Reuses the same store/seller lookup as the COD/UPI path above instead
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
-    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId);
     /*
      * Same supplier-of-record rule as `createOrderForGroup`, through the same
      * function. This path (PhonePe verify / webhook) is the SECOND place an
@@ -1572,7 +1680,44 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     const addons = storeAddons?.[firstItem.storeId] ?? {};
     const giftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates);
     const giftWrapMessage = addons.giftWrapMessage;
-    const shipmentProtectionFee = computeShipmentProtectionFee(groupTotal, addons.shipmentProtectionAddon ?? false, commissionRates);
+    /*
+     * 🛑 `computeProtectionFees`, not a bare `computeShipmentProtectionFee`.
+     *
+     * This path hand-rolled the shipment fee and computed NO sale-protection fee
+     * at all, which was wrong twice over:
+     *
+     *  1. **Sale protection was never charged here.** Razorpay's create-order
+     *     route DOES charge it (it calls `computeProtectionFees`), so the amount
+     *     captured and the amount this function records on the order disagreed
+     *     by the fee — and the platform absorbs the unconditional refund that
+     *     fee exists to pay for. See `computeSaleProtectionFee`.
+     *  2. **The C5e tiers were skipped.** The bare helper tests only "did the
+     *     buyer tick it" and the site-wide master switch, so shipment protection
+     *     could be billed on a seller who never agreed to back it, or on a
+     *     final-sale item where it cannot apply.
+     *
+     * Latent rather than live when written — `payment.phonepeEnabled` is false
+     * and the one live store has `supportsSaleProtection` unset — but both of
+     * those are a settings toggle away, and an under-charge that appears the
+     * moment a flag flips is worse than one that is visible now.
+     */
+    const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+    const { shippingProtectionFee: shipmentProtectionFee, saleProtectionFee } = computeProtectionFees({
+        subtotal: groupTotal,
+        selected: {
+            shipping: addons.shipmentProtectionAddon ?? false,
+            sale: addons.saleProtectionAddon ?? false,
+        },
+        tiers: {
+            platformShipping: commissionRates.shipmentProtectionFeeEnabled === true,
+            platformSale: commissionRates.saleProtectionFeeEnabled === true,
+            sellerShipping: storeProtections.shipping,
+            sellerSale: storeProtections.sale,
+            finalSale: groupHasFinalSale,
+        },
+        shippingFee: (s, sel) => computeShipmentProtectionFee(s, sel, commissionRates),
+        saleFee: (s, sel) => computeSaleProtectionFee(s, sel, commissionRates),
+    });
     /*
      * P-8 GST — now wired through this path. C0c defect 1.
      *
@@ -1605,7 +1750,7 @@ 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. */
-    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + platformFee + platformFeeGst;
+    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst;
     // 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
@@ -1694,6 +1839,9 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         giftWrapMessage: giftWrapFee > 0 ? giftWrapMessage?.slice(0, 500) : undefined,
         shipmentProtectionAddon: shipmentProtectionFee > 0 ? true : undefined,
         shipmentProtectionFee: shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
+        // 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,
         /*
          * The tax breakdown, matching `createOrderForGroup` field for field.
          * This path recorded NONE of it before C0c defect 1 — so an online order

package/dist/_internal/server/features/orders/actions.d.ts

@@ -46,3 +46,33 @@ export declare function adminRejectPaymentAsFraudAction(orderId: string, note: s
  * payment/order status — surfaces to the admin queue for investigation.
  */
 export declare function raiseOrderDisputeAction(orderId: string, reason: string): Promise<ActionResult<void>>;
+/**
+ * A buyer submits payment for ONE of their own EMI instalments.
+ *
+ * 🛑 Why this exists at all: there was no buyer-side route. The only writer
+ * was the seller's `markEmiInstallmentPaid`, so a buyer on an EMI plan could
+ * not pay an instalment — they waited for the seller to record it. The
+ * schema had anticipated them all along (`EmiInstallment.transactionId` and
+ * `.proofUrl` are documented as "buyer-uploaded"), which is the tell that the
+ * surface, not the model, was missing.
+ *
+ * 🛑 **ANY unpaid instalment, at ANY time — deliberately unbounded.** There is
+ * no due-date check and none should be added. A buyer who wants to clear the
+ * plan early is reducing our exposure, not breaking a rule, and the dueDate is
+ * the date we will CHASE them on, never the first date they may pay. Paying
+ * ahead also keeps `emiComplete` honest: that flag is what
+ * `assertEmiShippable` reads, so early settlement should be able to release a
+ * shipment early rather than waiting out a calendar.
+ *
+ * It mirrors the manual-payment model rather than inventing a second one: the
+ * buyer supplies a UTR and a proof, the seller or an admin confirms. The
+ * status therefore moves to `pending` review here, NOT to `paid` — a buyer
+ * must never be able to mark their own money received. `markEmiInstallmentPaid`
+ * stays the only writer of `paid`, and so stays the only way `emiComplete`
+ * can flip.
+ */
+export declare function submitEmiInstallmentPaymentAction(orderId: string, input: {
+    installmentIndex: number;
+    transactionId: string;
+    proofUrl?: string;
+}): Promise<ActionResult<void>>;

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

@@ -412,3 +412,106 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         });
     });
 }
+/**
+ * A buyer submits payment for ONE of their own EMI instalments.
+ *
+ * 🛑 Why this exists at all: there was no buyer-side route. The only writer
+ * was the seller's `markEmiInstallmentPaid`, so a buyer on an EMI plan could
+ * not pay an instalment — they waited for the seller to record it. The
+ * schema had anticipated them all along (`EmiInstallment.transactionId` and
+ * `.proofUrl` are documented as "buyer-uploaded"), which is the tell that the
+ * surface, not the model, was missing.
+ *
+ * 🛑 **ANY unpaid instalment, at ANY time — deliberately unbounded.** There is
+ * no due-date check and none should be added. A buyer who wants to clear the
+ * plan early is reducing our exposure, not breaking a rule, and the dueDate is
+ * the date we will CHASE them on, never the first date they may pay. Paying
+ * ahead also keeps `emiComplete` honest: that flag is what
+ * `assertEmiShippable` reads, so early settlement should be able to release a
+ * shipment early rather than waiting out a calendar.
+ *
+ * It mirrors the manual-payment model rather than inventing a second one: the
+ * buyer supplies a UTR and a proof, the seller or an admin confirms. The
+ * status therefore moves to `pending` review here, NOT to `paid` — a buyer
+ * must never be able to mark their own money received. `markEmiInstallmentPaid`
+ * stays the only writer of `paid`, and so stays the only way `emiComplete`
+ * can flip.
+ */
+export async function submitEmiInstallmentPaymentAction(orderId, input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const order = await orderRepository.findById(orderId);
+        if (!order)
+            throw new OrderNotFoundError(orderId);
+        if (!isAdminUser(user) && order.userId !== user.uid)
+            throw new OrderOwnershipError(orderId);
+        if (!order.emiEnabled)
+            throw new ValidationError("This order is not on an EMI plan");
+        const installments = order.emiInstallments ?? [];
+        const target = installments.find((i) => i.index === input.installmentIndex);
+        if (!target) {
+            throw new ValidationError(`Installment ${input.installmentIndex} not found on this order`);
+        }
+        if (target.status === "paid") {
+            throw new ValidationError("This installment is already paid");
+        }
+        // A second submission would overwrite the reference the reviewer is
+        // currently looking at, which reads to them as the buyer changing their
+        // story. Re-submitting needs the reviewer to reject the first one.
+        if (target.transactionId) {
+            throw new ValidationError("A payment reference is already under review for this installment");
+        }
+        /*
+         * 🛑 `status` is NOT written here, and writing it would be a lie dressed
+         * as a state change.
+         *
+         * A new instalment is created `status: "pending"` (see
+         * `createOrderForGroup`), so setting `"pending"` again changes nothing
+         * while reading like a transition — and it would leave "nobody has paid"
+         * and "the buyer has reported paying" indistinguishable, which is exactly
+         * the state a reviewer needs to tell apart.
+         *
+         * "Awaiting review" is DERIVED: `transactionId` set and `status !== "paid"`.
+         * Same rule as the manual-payment queue, which derives its four states
+         * from `paymentProofUrl` + `paymentReviewOutcome` rather than storing a
+         * mirror field that any write path could forget to update (Root Cause
+         * #42). Only `markEmiInstallmentPaid` writes `paid`, so a buyer can never
+         * mark their own money received, and `emiComplete` keeps its single writer.
+         */
+        const updatedInstallments = installments.map((i) => i.index === input.installmentIndex
+            ? { ...i, transactionId: input.transactionId, proofUrl: input.proofUrl }
+            : i);
+        await orderRepository.update(orderId, { emiInstallments: updatedInstallments });
+        /*
+         * Tell the seller there is something to confirm. Best-effort: a
+         * notification that fails must not lose the buyer's submitted reference,
+         * which is the only record that they paid.
+         */
+        const store = order.storeId ? await storeRepository.findById(order.storeId) : null;
+        if (store?.ownerId) {
+            await sendNotification({
+                userId: store.ownerId,
+                type: "payment_review",
+                /*
+                 * `high`, matching the other `payment_review` send in this file. The
+                 * two differ in urgency — that one has a 15-minute re-upload window
+                 * and this one has no deadline — but a single notification TYPE whose
+                 * priority disagrees between its call sites is the drift this codebase
+                 * keeps paying for, and unconfirmed money is a seller action item
+                 * either way.
+                 */
+                priority: "high",
+                title: "EMI instalment payment reported",
+                message: `A buyer has submitted payment for instalment ${input.installmentIndex} on order ${orderId}.`,
+                relatedId: orderId,
+                relatedType: "order",
+            }).catch((err) => {
+                void normalizeError(err);
+                serverLogger.error("Failed to notify seller of EMI instalment payment (non-fatal)", {
+                    orderId,
+                    installmentIndex: input.installmentIndex,
+                });
+            });
+        }
+    });
+}

package/dist/_internal/server/features/orders/adapters.js

@@ -170,6 +170,13 @@ export function orderDocumentToOrder(doc) {
         // the packer needs giftWrapMessage in hand. An
         // adapter that drops them makes every downstream surface render its
         // "not applicable" fallback instead (Root Cause #57).
+        // EMI, so the buyer can see and pay their own schedule. Mapped with the
+        // add-ons above for the same reason recorded there: an adapter that drops
+        // a field makes every downstream surface render its not-applicable
+        // fallback (Root Cause #57).
+        emiEnabled: doc.emiEnabled,
+        emiInstallments: doc.emiInstallments,
+        emiRemainingBalance: doc.emiRemainingBalance,
         giftWrapAddon: doc.giftWrapAddon,
         giftWrapFee: doc.giftWrapFee,
         giftWrapMessage: doc.giftWrapMessage,

package/dist/_internal/server/features/shipping/reconcile.d.ts

@@ -0,0 +1,28 @@
+import { type ActualShipmentCost } from "../../../shared/shipping/quote";
+export interface ReconcileShippingResult {
+    /** `null` when there was nothing to reconcile — see the reasons below. */
+    outcome: "credited" | "seller-absorbed" | "exact" | null;
+    sellerAbsorbs: number;
+    buyerPoints: number;
+    /** Why nothing happened, when `outcome` is null. For logs and the UI. */
+    skipped?: "no-quote" | "already-reconciled" | "no-buyer";
+}
+/**
+ * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.
+ *
+ * Crediting points is an APPEND to a ledger. Appends do not deduplicate
+ * themselves, so a dispatch action that fired twice — a double-clicked button,
+ * a retried job, a webhook delivered again — would pay the buyer twice, and
+ * nothing downstream could distinguish that from two genuine savings. The
+ * reconciliation record is written in the same step as the credit precisely so
+ * it can be the key.
+ *
+ * It deliberately does NOT use a transaction spanning the order and the
+ * ledger: `pointsRepository.append` already runs its own transaction over the
+ * ledger and the balance mirror, and nesting would mean reading the order
+ * inside it for no added safety. The residual risk is a crash between the
+ * credit and the order write, which leaves a credited buyer and an order that
+ * looks unreconciled — recoverable, and strictly better than the alternative
+ * ordering, which would mark the order done and then fail to pay.
+ */
+export declare function reconcileOrderShipping(orderId: string, actual: ActualShipmentCost): Promise<ReconcileShippingResult>;