tango-app-api-payment-subscription 3.5.17 → 3.5.18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.17",
+    "version": "3.5.18",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",
@@ -29,7 +29,7 @@
         "nodemon": "^3.1.0",
         "puppeteer": "^24.41.0",
         "swagger-ui-express": "^5.0.0",
-        "tango-api-schema": "^2.6.35",
+        "tango-api-schema": "^2.6.36",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
         "winston-daily-rotate-file": "^5.0.0",

package/scripts/create-billing-groups-by-country.js

@@ -36,7 +36,7 @@ import mongoose from 'mongoose';
 import 'dotenv/config';
 import { getConnection } from '../config/database/database.js';
 
-const DEFAULT_CLIENTS = [ '387', '193' ];
+const DEFAULT_CLIENTS = [ '387', '193', '11' ];
 
 // Fallback billing group for stores that have no storeProfile.country.
 const UNKNOWN_GROUP_NAME = 'Unknown';

package/src/controllers/billing.controllers.js

@@ -266,7 +266,37 @@ export const getAllBillingGroups = async ( req, res ) => {
   try {
     const billingGroups = await find( { clientId: req.query.clientId } );
 
-    return res.sendSuccess( billingGroups );
+    // Per group: does an ADVANCE invoice already cover the CURRENT month? If so,
+    // attach { invoice, period } so the Generate Invoice popup can show it (and
+    // signal a normal monthly invoice will be made instead of another advance).
+    const currentMonthLabel = dayjs().format( 'MMM YYYY' );
+    const enriched = await Promise.all( ( billingGroups || [] ).map( async ( g ) => {
+      const plain = g.toObject?.() || g;
+      let advanceCoverage = null;
+      try {
+        const adv = await invoiceService.findOne( {
+          'groupId': g._id,
+          'advanceInvoice': true,
+          'products.month': currentMonthLabel,
+        } );
+        if ( adv ) {
+          // Ordered distinct month labels across the advance invoice's line
+          // items → period "first to last" (e.g. "Jun-2026 to Aug-2026").
+          const months = [ ...new Set( ( adv.products || [] ).map( ( p ) => p.month ).filter( Boolean ) ) ];
+          months.sort( ( a, b ) => dayjs( a, 'MMM YYYY' ).valueOf() - dayjs( b, 'MMM YYYY' ).valueOf() );
+          const fmt = ( m ) => dayjs( m, 'MMM YYYY' ).format( 'MMM-YYYY' );
+          const period = months.length ?
+            ( months.length > 1 ? `${fmt( months[0] )} to ${fmt( months[months.length - 1] )}` : fmt( months[0] ) ) :
+            '';
+          advanceCoverage = { invoice: adv.invoice, period };
+        }
+      } catch ( e ) {
+        // Coverage is advisory only — never fail the group list over it.
+      }
+      return { ...plain, advanceCoverage };
+    } ) );
+
+    return res.sendSuccess( enriched );
   } catch ( error ) {
     logger.error( { error: error, function: 'getBillingGroups' } );
     return res.sendError( error, 500 );

package/src/controllers/brandsBilling.controller.js

@@ -1057,8 +1057,11 @@ export async function updateDailyPricingWorkingDays( req, res ) {
         { arrayFilters: [ { 'store.storeId': storeId }, { 'product.productName': productName } ] },
     );
 
-    if ( result.modifiedCount === 0 ) {
-      return res.sendError( 'Record not found or no changes made', 204 );
+    // Only a missing record is a real failure. matchedCount > 0 with
+    // modifiedCount 0 just means the value was already that number (e.g. saving
+    // 0 on an already-0 row) — treat that as success, not an error.
+    if ( ( result.matchedCount || 0 ) === 0 ) {
+      return res.sendError( 'Record not found', 404 );
     }
 
     const logObj = {

package/src/controllers/invoice.controller.js

@@ -19,6 +19,7 @@ import { findOneApplicationDefault } from '../services/applicationDefault.servic
 import * as assignedStoreService from '../services/assignedStore.service.js';
 import * as bankTransactionService from '../services/bankTransaction.service.js';
 import { getUsdInrRate, getAdditionalProducts } from './brandsBilling.controller.js';
+import { applyInvoiceToPurchaseOrder } from './purchaseOrder.controller.js';
 
 // Pulls CSM + Finance head emails (stored under applicationDefault
 // type=invoice, subType=heads) AND the per-client CSMs assigned via
@@ -126,8 +127,11 @@ export async function createInvoice( req, res ) {
         return res.sendError( 'clientId is required for customInvoice', 400 );
       }
       const Finacialyear = getCurrentFinancialYear();
+      // Quarterly/half-yearly/yearly advance invoices use the separate TINV-
+      // series with its own per-FY counter; monthly advance + normal stay INV-.
+      const invPrefix = invoicePrefixFor( req.body.advanceInvoice, req.body.advancePeriod );
       const previousinvoice = await invoiceService.findandsort(
-          { invoice: { $regex: `^INV-${Finacialyear}-` } },
+          { invoice: { $regex: `^${invPrefix}${Finacialyear}-` } },
           {},
           { invoiceIndex: -1 },
       );
@@ -167,7 +171,7 @@ export async function createInvoice( req, res ) {
         Math.round( Number( req.body.totalAmount ) || 0 );
 
       const data = {
-        invoice: `INV-${Finacialyear}-${invoiceNo}`,
+        invoice: `${invPrefix}${Finacialyear}-${invoiceNo}`,
         invoiceIndex: invoiceNo,
         clientId: req.body.clientId,
         groupId: req.body.groupId || undefined,
@@ -192,8 +196,24 @@ export async function createInvoice( req, res ) {
         advanceInvoice: req.body.advanceInvoice || false,
         advancePeriod: req.body.advanceInvoice ? ( req.body.advancePeriod || 'monthly' ) : undefined,
         advanceMonths: customAdvanceMonths,
+        // Purchase order this invoice is mapped to (optional).
+        purchaseOrderNumber: req.body.purchaseOrderNumber || undefined,
       };
       const created = await invoiceService.create( data );
+      // Map to a PO (deduct its remaining balance + log) when one was picked.
+      if ( data.purchaseOrderNumber ) {
+        try {
+          await applyInvoiceToPurchaseOrder( {
+            clientId: data.clientId,
+            purchaseOrderNumber: data.purchaseOrderNumber,
+            invoice: data.invoice,
+            amount: data.totalAmount,
+            req,
+          } );
+        } catch ( poErr ) {
+          logger.error( { error: poErr, function: 'createInvoice.applyPO', invoice: data.invoice } );
+        }
+      }
       const logObj = {
         userName: req.user?.userName,
         email: req.user?.email,
@@ -216,11 +236,41 @@ export async function createInvoice( req, res ) {
 
     for ( let group of invoiceGroupList ) {
       let Finacialyear = getCurrentFinancialYear();
-      // Scope the highest-index lookup to invoices created in the current FY
-      // (invoice IDs are `INV-${FY}-${index}`). Without this scope the new FY
-      // would continue the previous year's sequence instead of resetting.
+
+      // If an ADVANCE invoice already covers the CURRENT month for this group
+      // (i.e. it has a product line item labelled with the current MMM YYYY),
+      // we must NOT generate another advance invoice for it. Instead generate a
+      // normal monthly invoice using the store counts from that advance invoice.
+      const currentMonthLabel = dayjs().format( 'MMM YYYY' );
+      let advanceCoverProducts = null;
+      if ( group.advanceInvoice ) {
+        const existingAdvance = await invoiceService.findOne( {
+          'groupId': group._id,
+          'advanceInvoice': true,
+          'products.month': currentMonthLabel,
+        } );
+        if ( existingAdvance ) {
+          // Take this month's line items from the advance invoice (they carry the
+          // store counts + prices the advance covered) and bill them as a normal
+          // monthly invoice.
+          advanceCoverProducts = ( existingAdvance.products || [] )
+              .filter( ( p ) => p.month === currentMonthLabel )
+              .map( ( p ) => ( { ...( p._doc || p ), month: currentMonthLabel } ) );
+        }
+      }
+      // Effective advance flag: forced OFF when an advance invoice already covers
+      // this month, so the rest of the loop runs the normal monthly path.
+      const isAdvance = group.advanceInvoice && !advanceCoverProducts;
+
+      // Quarterly/half-yearly/yearly advance invoices use the separate TINV-
+      // series with its own per-FY counter; monthly advance + normal stay INV-.
+      const invPrefix = invoicePrefixFor( isAdvance, group.advancePeriod );
+      // Scope the highest-index lookup to invoices created in the current FY for
+      // THIS series. Without the FY scope the new FY would continue the previous
+      // year's sequence; without the prefix scope the two series would share one
+      // counter.
       let previousinvoice = await invoiceService.findandsort(
-          { invoice: { $regex: `^INV-${Finacialyear}-` } },
+          { invoice: { $regex: `^${invPrefix}${Finacialyear}-` } },
           {},
           { invoiceIndex: -1 },
       );
@@ -232,10 +282,16 @@ export async function createInvoice( req, res ) {
 
       let address = group.addressLineOne + group.addressLineTwo + group.city + ',' + group.state + ',' + group.country + ' -' + group.pinCode;
       let getClient = await clientService.findOne( { clientId: group.clientId, status: 'active' } );
-      let baseDate = group.advanceInvoice ? dayjs().add( 1, 'month' ).startOf( 'month' ) : dayjs();
+      // Advance bills next month; normal (incl. the advance-already-covered case)
+      // bills the current month.
+      let baseDate = isAdvance ? dayjs().add( 1, 'month' ).startOf( 'month' ) : dayjs();
       let products;
 
-      if ( getClient?.priceType === 'standard' ) {
+      if ( advanceCoverProducts ) {
+        // Reuse the advance invoice's current-month line items (store counts +
+        // prices already set) and bill them as a normal monthly invoice.
+        products = advanceCoverProducts;
+      } else if ( getClient?.priceType === 'standard' ) {
         products = await standardPrice( group, getClient, baseDate );
       } else {
         products = await stepPrice( group, getClient );
@@ -247,18 +303,22 @@ export async function createInvoice( req, res ) {
       // store-based product lines. Added BEFORE the multi-month expansion below
       // so they repeat per month and are included in the taxable subtotal, just
       // like the standard products. Returns [] for any client without extras.
-      const extraProducts = await getAdditionalProducts( group.clientId );
-      for ( const ep of extraProducts ) {
-        products.push( {
-          productName: ep.productName,
-          period: 'fullmonth',
-          storeCount: ep.quantity,
-          amount: ep.total,
-          price: ep.price,
-          description: ep.productName,
-          HsnNumber: '998314',
-          month: baseDate.format( 'MMM YYYY' ),
-        } );
+      // Skip when reusing advance-invoice line items — those already include any
+      // additional products from when the advance invoice was generated.
+      if ( !advanceCoverProducts ) {
+        const extraProducts = await getAdditionalProducts( group.clientId );
+        for ( const ep of extraProducts ) {
+          products.push( {
+            productName: ep.productName,
+            period: 'fullmonth',
+            storeCount: ep.quantity,
+            amount: ep.total,
+            price: ep.price,
+            description: ep.productName,
+            HsnNumber: '998314',
+            month: baseDate.format( 'MMM YYYY' ),
+          } );
+        }
       }
 
       // Billing horizon in months. Advance and normal cycle are independent —
@@ -269,13 +329,15 @@ export async function createInvoice( req, res ) {
       // product is repeated once per month, labelled with that month, at the
       // normal monthly amount. One invoice then bills the whole period.
       // (advancePeriod uses 'halfyearly'; paymentCycle uses 'quarter'/'halfYearly'
-      // — map both spellings.)
+      // — map both spellings.) Uses isAdvance (not group.advanceInvoice) so the
+      // advance-already-covered case bills a single normal month.
       const advancePeriodMonths = { quarterly: 3, halfyearly: 6, yearly: 12 };
       const paymentCycleMonths = { quarter: 3, quarterly: 3, halfYearly: 6, halfyearly: 6, yearly: 12 };
-      const advanceMonths = group.advanceInvoice ?
+      const advanceMonths = isAdvance ?
         ( advancePeriodMonths[group.advancePeriod] || 1 ) :
         ( paymentCycleMonths[group.paymentCycle] || 1 );
-      if ( advanceMonths > 1 ) {
+      // No re-expansion when reusing advance line items (already this month only).
+      if ( !advanceCoverProducts && advanceMonths > 1 ) {
         const expanded = [];
         for ( let m = 0; m < advanceMonths; m++ ) {
           const monthLabel = baseDate.add( m, 'month' ).format( 'MMM YYYY' );
@@ -415,6 +477,36 @@ export async function createInvoice( req, res ) {
 
       ] );
 
+      // For TINV (advance quarterly/half-yearly/yearly) invoices, capture the
+      // actual store list — storeId, storeName and each store's products with
+      // working days — onto the invoice from the latest daily-pricing doc.
+      let storeDetails = [];
+      if ( invPrefix === 'TINV-' ) {
+        const dpDoc = await dailyPricingService.aggregate( [
+          { $match: { clientId: group.clientId } },
+          { $sort: { dateISO: -1 } },
+          { $limit: 1 },
+          { $project: { stores: {
+            $filter: { input: '$stores', as: 'item', cond: { $in: [ '$$item.storeId', group.stores ] } },
+          } } },
+        ] );
+        const dpStores = dpDoc?.[0]?.stores || [];
+        storeDetails = dpStores
+            .map( ( s ) => ( {
+              storeId: s.storeId,
+              storeName: s.storeName,
+              // Only products that actually ran this month (workingdays > 0).
+              products: ( s.products || [] )
+                  .filter( ( p ) => ( Number( p.workingdays ) || 0 ) > 0 )
+                  .map( ( p ) => ( {
+                    productName: p.productName,
+                    workingdays: Number( p.workingdays ) || 0,
+                  } ) ),
+            } ) )
+            // Drop stores left with no running products.
+            .filter( ( s ) => s.products.length > 0 );
+      }
+
       // billingDate is the actual invoice (creation) date — even for advance
       // invoices. The advance MONTH is reflected only in the product lines /
       // monthOfbilling (driven by baseDate), not in the billing date itself.
@@ -428,7 +520,7 @@ export async function createInvoice( req, res ) {
       let data = {
         groupName: group.groupName,
         groupId: group._id,
-        invoice: req.body.invoiceId ? req.body.invoiceId : `INV-${Finacialyear}-${invoiceNo}`,
+        invoice: req.body.invoiceId ? req.body.invoiceId : `${invPrefix}${Finacialyear}-${invoiceNo}`,
         products: products,
         status: 'pendingCsm',
         amount: Math.round( amount ),
@@ -442,12 +534,19 @@ export async function createInvoice( req, res ) {
         clientId: group.clientId,
         paymentMethod: 'Online',
         billingDate: new Date( invoicedate ),
-        stores: totalStoreCount.length ? totalStoreCount[0].stores.length : 0,
+        // For the advance-already-covered case, take the store count from the
+        // advance invoice's line items; otherwise the live running-store count.
+        stores: advanceCoverProducts ?
+          Math.max( 0, ...advanceCoverProducts.map( ( p ) => Number( p.storeCount ) || 0 ) ) :
+          ( totalStoreCount.length ? totalStoreCount[0].stores.length : 0 ),
+        // TINV invoices carry the full store list (id, name, product workingdays).
+        storeDetails: storeDetails,
         currency: group.currency ? group.currency : 'inr',
         monthOfbilling: baseDate.format( 'MM' ),
         dueDate: dueDate,
-        advanceInvoice: group.advanceInvoice || false,
-        advancePeriod: group.advanceInvoice ? ( group.advancePeriod || 'monthly' ) : undefined,
+        // Stored as a NORMAL invoice when an advance already covered this month.
+        advanceInvoice: isAdvance || false,
+        advancePeriod: isAdvance ? ( group.advancePeriod || 'monthly' ) : undefined,
         advanceMonths: advanceMonths,
       };
 
@@ -476,12 +575,12 @@ export async function createInvoice( req, res ) {
         await invoiceService.create( data );
 
         if ( !req.body.regenrate ) {
-          let invoiceType = group.advanceInvoice ? 'advance' : '';
+          let invoiceType = isAdvance ? 'advance' : '';
           let logObj = {
             userName: req.user?.userName,
             email: req.user?.email,
             clientId: group.clientId,
-            logSubType: group.advanceInvoice ? 'advanceInvoiceCreated' : 'invoiceCreated',
+            logSubType: isAdvance ? 'advanceInvoiceCreated' : 'invoiceCreated',
             logType: 'invoice',
             date: new Date(),
             changes: [ `${data.invoice} ${invoiceType} invoice has been generated for ${group.groupName} for ${baseDate.format( 'MMM YYYY' )}` ],
@@ -511,6 +610,17 @@ function getCurrentFinancialYear() {
   }
 }
 
+// Invoice-number prefix. Advance invoices for quarterly / half-yearly / yearly
+// use a separate "TINV-" series with its own counter; everything else
+// (including MONTHLY advance) uses the normal "INV-" series.
+function invoicePrefixFor( advanceInvoice, advancePeriod ) {
+  const multiMonth = [ 'quarterly', 'halfyearly', 'yearly' ];
+  if ( advanceInvoice && multiMonth.includes( String( advancePeriod || '' ).toLowerCase() ) ) {
+    return 'TINV-';
+  }
+  return 'INV-';
+}
+
 
 // ---------------------------------------------------------------------------
 // Shared annexure builder. Anchored to the invoice's BILLING month and
@@ -707,7 +817,7 @@ export async function invoiceDownload( req, res ) {
         companyAddress: invoiceInfo.companyAddress,
         PlaceOfSupply: invoiceInfo.PlaceOfSupply,
         GSTNumber: invoiceInfo.GSTNumber,
-        PoNum: getgroup?.po,
+        PoNum: invoiceInfo.purchaseOrderNumber || getgroup?.po || '',
         amountwords: AmountinWords,
         Terms: `Term ${getgroup?.paymentTerm ? getgroup?.paymentTerm : '30'}`,
         currencyType: invoiceCurrency,
@@ -903,7 +1013,7 @@ async function buildInvoicePdfBuffer( invoiceId ) {
     companyAddress: invoiceInfo.companyAddress,
     PlaceOfSupply: invoiceInfo.PlaceOfSupply,
     GSTNumber: invoiceInfo.GSTNumber,
-    PoNum: getgroup?.po,
+    PoNum: invoiceInfo.purchaseOrderNumber || getgroup?.po || '',
     amountwords: AmountinWords,
     Terms: `Term ${getgroup?.paymentTerm ? getgroup?.paymentTerm : '30'}`,
     currencyType: invoiceCurrency,
@@ -2521,7 +2631,14 @@ export async function checkPaymentStatus( req, res ) {
 
 export async function getInvoice( req, res ) {
   try {
-    let invoice = await invoiceService.findOne( { _id: req.params.invoiceId } );
+    // Accept either a Mongo _id or an invoice NUMBER. A 24-char hex string is
+    // treated as an _id; anything else (e.g. "INV-2026-00012") matches the
+    // invoice number — so the Purchase Order popup can preview by number.
+    const idParam = String( req.params.invoiceId || '' );
+    const isObjectId = /^[a-fA-F0-9]{24}$/.test( idParam );
+    let invoice = await invoiceService.findOne(
+        isObjectId ? { _id: idParam } : { invoice: idParam },
+    );
     if ( !invoice ) {
       return res.sendError( 'Invoice not found', 404 );
     }
@@ -2551,7 +2668,7 @@ export async function updateInvoice( req, res ) {
       'companyName', 'companyAddress', 'GSTNumber', 'PlaceOfSupply',
       'groupName', 'groupId', 'stores', 'billingDate', 'dueDate',
       'currency', 'status', 'paymentStatus', 'products', 'tax',
-      'amount', 'totalAmount', 'paymentMethod',
+      'amount', 'totalAmount', 'paymentMethod', 'purchaseOrderNumber',
     ];
 
     allowedFields.forEach( ( field ) => {
@@ -2577,6 +2694,23 @@ export async function updateInvoice( req, res ) {
 
     let updatedInvoice = await invoiceService.updateOne( { _id: req.body._id }, updateData );
 
+    // PO mapping on edit: when a (new) PO number is set, deduct the invoice
+    // amount from that PO. applyInvoiceToPurchaseOrder is idempotent per
+    // invoice+PO, so re-saving the same PO won't double-deduct.
+    if ( updateData.purchaseOrderNumber && updateData.purchaseOrderNumber !== invoice.purchaseOrderNumber ) {
+      try {
+        await applyInvoiceToPurchaseOrder( {
+          clientId: invoice.clientId,
+          purchaseOrderNumber: updateData.purchaseOrderNumber,
+          invoice: invoice.invoice,
+          amount: updateData.totalAmount != null ? updateData.totalAmount : invoice.totalAmount,
+          req,
+        } );
+      } catch ( poErr ) {
+        logger.error( { error: poErr, function: 'updateInvoice.applyPO', invoice: invoice.invoice } );
+      }
+    }
+
     let logObj = {
       userName: req.user?.userName,
       email: req.user?.email,

package/src/controllers/purchaseOrder.controller.js

@@ -0,0 +1,171 @@
+import * as purchaseOrderService from '../services/purchaseOrder.service.js';
+import { logger, insertOpenSearchData, fileUpload, customSignedUrl } from 'tango-app-api-middleware';
+
+// Derive PO status from how much of it has been consumed.
+function statusFor( totalAmount, remainingAmount ) {
+  if ( remainingAmount <= 0 ) {
+    return 'fullyUsed';
+  }
+  if ( remainingAmount < totalAmount ) {
+    return 'partiallyUsed';
+  }
+  return 'open';
+}
+
+function logPO( req, clientId, subType, changes ) {
+  try {
+    const logObj = {
+      userName: req.user?.userName,
+      email: req.user?.email,
+      clientId: clientId,
+      logSubType: subType,
+      logType: 'purchaseOrder',
+      date: new Date(),
+      changes: changes,
+      eventType: '',
+      timestamp: new Date(),
+      showTo: [ 'tango' ],
+    };
+    insertOpenSearchData( JSON.parse( process.env.OPENSEARCH ).activityLog, logObj );
+  } catch ( e ) {
+    logger.error( { error: e, function: 'logPO' } );
+  }
+}
+
+// Create a purchase order. remainingAmount starts equal to totalAmount.
+export async function createPurchaseOrder( req, res ) {
+  try {
+    const clientId = String( req.body?.clientId || '' );
+    const companyName = String( req.body?.companyName || '' ).trim();
+    const purchaseOrderNumber = String( req.body?.purchaseOrderNumber || '' ).trim();
+    const totalAmount = Number( req.body?.totalAmount ) || 0;
+    const date = req.body?.date ? new Date( req.body.date ) : new Date();
+
+    if ( !clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+    if ( !purchaseOrderNumber ) {
+      return res.sendError( 'purchaseOrderNumber is required', 400 );
+    }
+    if ( !( totalAmount > 0 ) ) {
+      return res.sendError( 'totalAmount must be greater than 0', 400 );
+    }
+
+    // Prevent duplicate PO numbers for the same client.
+    const existing = await purchaseOrderService.findOne( { clientId, purchaseOrderNumber } );
+    if ( existing ) {
+      return res.sendError( 'A purchase order with this number already exists', 409 );
+    }
+
+    // Optional PO PDF upload (multer single 'file') → assets bucket, same as
+    // brand document upload. PDF only.
+    let pdfPath = '';
+    const file = req.file;
+    if ( file ) {
+      if ( file.mimetype !== 'application/pdf' ) {
+        return res.sendError( 'Only PDF files are allowed', 400 );
+      }
+      const bucket = JSON.parse( process.env.BUCKET );
+      const safeName = purchaseOrderNumber.replace( /[^a-zA-Z0-9-_]/g, '_' );
+      const fileName = `${safeName}_${Date.now()}.pdf`;
+      const key = `${clientId}/purchase-orders/`;
+      let result = await fileUpload( {
+        Bucket: bucket.assets,
+        Key: key,
+        fileName: fileName,
+        ContentType: file.mimetype,
+        body: file.buffer,
+      } );
+      pdfPath = `${key}${fileName}`;
+      console.log( '🚀 ~ createPurchaseOrder ~ result:', result );
+    }
+
+    const created = await purchaseOrderService.create( {
+      clientId,
+      companyName,
+      purchaseOrderNumber,
+      totalAmount,
+      remainingAmount: totalAmount,
+      date,
+      status: 'open',
+      usage: [],
+      pdfPath,
+      createdBy: req.user?.email || req.user?.userName || '',
+    } );
+
+    logPO( req, clientId, 'purchaseOrderCreated', [ `PO ${purchaseOrderNumber} created with amount ${totalAmount}` ] );
+    return res.sendSuccess( created );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'createPurchaseOrder' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+// List a client's purchase orders (newest first).
+export async function getPurchaseOrders( req, res ) {
+  try {
+    const clientId = String( req.query?.clientId || req.params?.clientId || '' );
+    if ( !clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+    const orders = await purchaseOrderService.find( { clientId } );
+    const sorted = ( orders || [] ).sort( ( a, b ) =>
+      new Date( b.createdAt || b.date || 0 ) - new Date( a.createdAt || a.date || 0 ) );
+    // Attach a signed URL for any uploaded PO PDF (assets bucket).
+    const bucket = JSON.parse( process.env.BUCKET );
+    const withUrls = await Promise.all( sorted.map( async ( o ) => {
+      const plain = o.toObject?.() || o;
+      let pdfUrl = '';
+      if ( plain.pdfPath ) {
+        try {
+          pdfUrl = await customSignedUrl( { Bucket: bucket.assets, file_path: plain.pdfPath }, 8 );
+        } catch ( e ) {
+          pdfUrl = '';
+        }
+      }
+      return { ...plain, pdfUrl };
+    } ) );
+    return res.sendSuccess( { purchaseOrders: withUrls } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'getPurchaseOrders' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+// Map an invoice to a PO: deduct the invoice amount from the PO's remaining
+// balance, record the usage, update status, and log it. Shared with invoice
+// generation/edit so the deduction happens wherever an invoice gets a PO.
+// Returns the updated PO doc, or throws on a missing PO.
+export async function applyInvoiceToPurchaseOrder( { clientId, purchaseOrderNumber, invoice, amount, req } ) {
+  if ( !purchaseOrderNumber ) {
+    return null;
+  }
+  const po = await purchaseOrderService.findOne( { clientId, purchaseOrderNumber } );
+  if ( !po ) {
+    logger.error( { function: 'applyInvoiceToPurchaseOrder', message: 'PO not found', clientId, purchaseOrderNumber } );
+    return null;
+  }
+  // Idempotency: if this invoice is already mapped to this PO, don't double-deduct.
+  const alreadyMapped = ( po.usage || [] ).some( ( u ) => u.invoice === invoice );
+  if ( alreadyMapped ) {
+    return po;
+  }
+  const amt = Number( amount ) || 0;
+  const remainingAmount = Math.round( ( ( po.remainingAmount || 0 ) - amt ) * 100 ) / 100;
+  const usage = ( po.usage || [] ).concat( [ {
+    invoice,
+    amount: amt,
+    mappedAt: new Date(),
+    mappedBy: req?.user?.email || req?.user?.userName || '',
+  } ] );
+  const status = statusFor( po.totalAmount || 0, remainingAmount );
+  await purchaseOrderService.updateOne(
+      { clientId, purchaseOrderNumber },
+      { remainingAmount, usage, status },
+  );
+  if ( req ) {
+    logPO( req, clientId, 'purchaseOrderInvoiceMapped',
+        [ `Invoice ${invoice} mapped to PO ${purchaseOrderNumber}; ${amt} deducted, remaining ${remainingAmount}` ] );
+  }
+  return { ...po.toObject?.() || po, remainingAmount, usage, status };
+}

package/src/routes/billing.routes.js

@@ -1,8 +1,11 @@
 import express from 'express';
+import multer from 'multer';
 export const billingRouter = express.Router();
+const poUpload = multer( { storage: multer.memoryStorage(), limits: { fileSize: 10 * 1024 * 1024 } } );
 import { accessVerification, isAllowedSessionHandler, validate } from 'tango-app-api-middleware';
 import { getPaymentReminder, savePaymentReminder } from '../controllers/paymentReminder.controller.js';
 import { triggerPaymentReminders } from '../controllers/paymentReminderTrigger.controller.js';
+import { createPurchaseOrder, getPurchaseOrders } from '../controllers/purchaseOrder.controller.js';
 import { createBillingGroup, deleteBillingGroup, getAllBillingGroups, getBillingGroups, getClientProducts, getInvoices, getLeadProducts, getBaseProducts, onetimePayment, subscribedStoreList, updateBillingGroup, gstinLookup } from '../controllers/billing.controllers.js';
 import { billingGroupSchema, clientProductsValid, createBillingGroupsSchema, deleteBillingGroupsSchema, getBillingGroupsSchema, getInvoiceSchema, leadProductsValid, onetimeFeeValid, subscribedStoreListSchema, updateBillingGroupsSchema } from '../dtos/validation.dtos.js';
 
@@ -37,6 +40,10 @@ billingRouter.get( '/gst-lookup/:gstin', isAllowedSessionHandler, accessVerifica
 billingRouter.get( '/payment-reminder/:clientId', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), getPaymentReminder );
 billingRouter.post( '/payment-reminder', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), savePaymentReminder );
 
+// Purchase Orders (brand-view Purchase Order tab).
+billingRouter.get( '/purchase-orders', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), getPurchaseOrders );
+billingRouter.post( '/purchase-orders', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), poUpload.single( 'file' ), createPurchaseOrder );
+
 // Cron-triggered: sends the configured payment reminder emails. Unauthenticated
 // like the other cron endpoints; protect at the network / scheduler layer.
 billingRouter.post( '/payment-reminder/trigger', triggerPaymentReminders );

package/src/services/purchaseOrder.service.js

@@ -0,0 +1,21 @@
+import model from 'tango-api-schema';
+
+export const find = ( query = {}, record = {} ) => {
+  return model.purchaseOrderModel.find( query, record );
+};
+
+export const findOne = ( query = {}, record = {} ) => {
+  return model.purchaseOrderModel.findOne( query, record );
+};
+
+export const create = ( record ) => {
+  return model.purchaseOrderModel.create( record );
+};
+
+export const updateOne = ( query, record ) => {
+  return model.purchaseOrderModel.updateOne( query, { $set: record } );
+};
+
+export const aggregate = ( query = [] ) => {
+  return model.purchaseOrderModel.aggregate( query );
+};