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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.16",
+    "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.34",
+        "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 = {
@@ -2270,3 +2273,330 @@ export async function additionalProducts( req, res ) {
     return res.sendError( error, 500 );
   }
 }
+
+// POST a JSON payload to a Lambda Function URL and return the parsed JSON
+// (or false on failure). Node's fetch forbids a body on GET, so POST is used.
+async function lamdaServiceCall( url, data ) {
+  try {
+    const response = await fetch( url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify( data ),
+      signal: AbortSignal.timeout( 300000 ),
+    } );
+    if ( !response.ok ) {
+      throw new Error( `Response status: ${response.status}` );
+    }
+    return await response.json();
+  } catch ( error ) {
+    logger.error( { error: error, message: data, function: 'lamdaServiceCall' } );
+    return false;
+  }
+}
+
+// Unit price for a product from the latest billing_details OpenSearch record.
+// productName match is case-insensitive. Returns 0 if not found / unavailable.
+async function billingDetailsPrice( clientId, productName ) {
+  try {
+    const osRes = await getOpenSearchData( BILLING_DETAILS_INDEX, {
+      size: 1,
+      query: { term: { 'client_id': clientId } },
+      sort: [ { date_string: { order: 'desc' } } ],
+    } );
+    const hits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
+    const match = ( hits[0]?._source?.products || [] )
+        .find( ( p ) => String( p.productName ).toLowerCase() === String( productName ).toLowerCase() );
+    return Number( match?.price ) || 0;
+  } catch ( osErr ) {
+    logger.error( { error: osErr, function: 'billingDetailsPrice', clientId, productName } );
+    return 0;
+  }
+}
+
+// Build the Lambda-backed export rows (VMS / Run AI / etc.). Calls the product's
+// Lambda for store_names (storeIds), maps them to the stores collection for
+// name + country (Zone), with current-month days and the billing_details price.
+async function lambdaStoreExport( clientId, lambdaUrl, billingProductName ) {
+  const toDate = dayjs().format( 'DD-MM-YYYY' );
+  const lambdaResult = await lamdaServiceCall( lambdaUrl, { to_date: toDate, client_id: clientId } );
+  console.log( '🚀 ~ lambdaStoreExport ~ lambdaResult:', lambdaResult );
+  // These Lambdas return the storeIds under either `store_ids` (Run AI) or
+  // `store_names` (VMS) with no status_code. Accept whichever is present; data
+  // availability = a non-empty array.
+  const rawIds = ( lambdaResult && Array.isArray( lambdaResult.store_ids ) ) ? lambdaResult.store_ids :
+    ( ( lambdaResult && Array.isArray( lambdaResult.store_names ) ) ? lambdaResult.store_names : [] );
+  const storeIds = rawIds.map( ( s ) => String( s ) );
+  if ( !storeIds.length ) {
+    return [];
+  }
+  const price = await billingDetailsPrice( clientId, billingProductName );
+  const daysInMonth = dayjs().daysInMonth();
+  const stores = await storeService.find(
+      { clientId: clientId, storeId: { $in: storeIds } },
+      { 'storeId': 1, 'storeName': 1, 'storeProfile.country': 1 },
+  );
+  const byId = new Map( stores.map( ( s ) => [ String( s.storeId ), s ] ) );
+  return storeIds.map( ( id ) => {
+    const s = byId.get( String( id ) );
+    return {
+      'Store Names': s?.storeName || id,
+      'No of Days to be billed': daysInMonth,
+      'Final Amount': price,
+      'Zone': s?.storeProfile?.country || '',
+    };
+  } );
+}
+
+// tangoTraffic working days per store, from the latest daily-pricing doc.
+// Map<storeId, workingdays>; stores with no tangoTraffic record are absent.
+async function tangoTrafficDaysByStore( clientId ) {
+  const rows = await dailyPriceService.aggregate( [
+    { $match: { clientId: clientId } },
+    { $sort: { dateISO: -1 } },
+    { $limit: 1 },
+    { $unwind: '$stores' },
+    { $unwind: '$stores.products' },
+    { $match: { 'stores.products.productName': 'tangoTraffic' } },
+    { $group: { _id: '$stores.storeId', days: { $max: '$stores.products.workingdays' } } },
+  ] );
+  const map = new Map();
+  for ( const r of rows ) {
+    map.set( String( r._id ), r.days || 0 );
+  }
+  return map;
+}
+
+// Per-product detailed Excel export for the Additional Products section.
+// product selected via req.body.product / req.query.product. Eyetest is the
+// first; more products plug into the switch as their queries arrive.
+export async function additionalProductExport( req, res ) {
+  try {
+    const clientId = String( req.body?.clientId ?? req.query?.clientId ?? '' );
+    const product = String( req.body?.product ?? req.query?.product ?? '' ).toLowerCase();
+    // Optional date (YYYY-MM-DD) passed from the UI; defaults to today. Used by
+    // products that report by a specific day (e.g. Remote Optum).
+    const reqDate = String( req.body?.date ?? req.query?.date ?? '' ) || dayjs().format( 'YYYY-MM-DD' );
+    if ( !clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+
+    if ( product === 'eyetest' ) {
+      // Eye-test streams joined to their store, grouped per store to a stream
+      // count; enriched with store name, country (Zone) and the store's
+      // tangoTraffic working days (No of Days to be billed).
+      const streamRows = await cameraService.aggregate( [
+        { $match: { $and: [
+          { clientId: clientId },
+          { isEyeTestStream: true },
+          { qrCode: { $exists: true } },
+        ] } },
+        { $lookup: {
+          from: 'stores',
+          let: { storeId: '$storeId' },
+          pipeline: [ { $match: { $expr: { $and: [ { $eq: [ '$storeId', '$$storeId' ] } ] } } } ],
+          as: 'stores',
+        } },
+        { $unwind: { path: '$stores', preserveNullAndEmptyArrays: true } },
+        { $group: {
+          _id: '$storeId',
+          streamCount: { $sum: 1 },
+          storeName: { $first: '$stores.storeName' },
+          country: { $first: '$stores.storeProfile.country' },
+        } },
+        { $sort: { storeName: 1 } },
+      ] );
+
+      const daysMap = await tangoTrafficDaysByStore( clientId );
+      const price = ADDITIONAL_PRODUCT_PRICES.eyetest;
+      const exportData = streamRows.map( ( r ) => {
+        const streamCount = r.streamCount || 0;
+        const days = daysMap.get( String( r._id ) ) || 0;
+        // Amount = streams x price (no proration).
+        return {
+          'storeId': r._id,
+          'storeName': r.storeName || '',
+          'Stream Count': streamCount,
+          'No of Days to be billed': days,
+          'Amount': streamCount * price,
+          'Zone': r.country || '',
+        };
+      } );
+
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    if ( product === 'planogram' ) {
+      // Unique storeName from the planograms collection, enriched with the
+      // store's country (Zone) and tangoTraffic working days. Amount is the
+      // flat planogram price per store.
+      const planoRows = await planogramService.aggregate( [
+        { $match: { clientId: clientId } },
+        { $group: { _id: '$storeName', storeId: { $first: '$storeId' } } },
+        { $lookup: {
+          from: 'stores',
+          let: { sid: '$storeId' },
+          pipeline: [ { $match: { $expr: { $eq: [ '$storeId', '$$sid' ] } } } ],
+          as: 'store',
+        } },
+        { $unwind: { path: '$store', preserveNullAndEmptyArrays: true } },
+        { $project: { _id: 0, storeName: '$_id', storeId: 1, country: '$store.storeProfile.country' } },
+        { $sort: { storeName: 1 } },
+      ] );
+
+      const price = ADDITIONAL_PRODUCT_PRICES.planogram;
+      // Planogram bills the full current month — every store shows the number of
+      // days in the current calendar month (not per-store working days).
+      const daysInMonth = dayjs().daysInMonth();
+      const exportData = planoRows.map( ( r ) => {
+        // Amount = flat planogram price per store (no proration).
+        return {
+          'storeName': r.storeName || '',
+          'No of Days to be billed': daysInMonth,
+          'Amount': price,
+          'Zone': r.country || '',
+        };
+      } );
+
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    if ( product === 'aimanager' ) {
+      // AI Manager bills the same stores as tangoTraffic running > 1 day. One
+      // row per such store with its tangoTraffic working days (No of Days to be
+      // billed), the flat AI Manager price, and the store's country (Zone).
+      const aiRows = await dailyPriceService.aggregate( [
+        { $match: { clientId: clientId } },
+        { $sort: { dateISO: -1 } },
+        { $limit: 1 },
+        { $unwind: '$stores' },
+        { $unwind: '$stores.products' },
+        { $match: { 'stores.products.productName': 'tangoTraffic', 'stores.products.workingdays': { $gt: 1 } } },
+        { $group: {
+          _id: '$stores.storeId',
+          storeName: { $first: '$stores.storeName' },
+          days: { $max: '$stores.products.workingdays' },
+        } },
+        { $lookup: {
+          from: 'stores',
+          let: { sid: '$_id' },
+          pipeline: [ { $match: { $expr: { $eq: [ '$storeId', '$$sid' ] } } } ],
+          as: 'store',
+        } },
+        { $unwind: { path: '$store', preserveNullAndEmptyArrays: true } },
+        { $project: { _id: 0, storeId: '$_id', storeName: 1, days: 1, country: '$store.storeProfile.country' } },
+        { $sort: { storeName: 1 } },
+      ] );
+
+      const price = ADDITIONAL_PRODUCT_PRICES.aiManager;
+      const exportData = aiRows.map( ( r ) => {
+        // Amount = flat AI Manager price per store (no proration).
+        return {
+          'Store Name': r.storeName || '',
+          'No of Days to be billed': r.days || 0,
+          'Final Amount': price,
+          'Zone': r.country || '',
+        };
+      } );
+
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    if ( product === 'vms' ) {
+      const exportData = await lambdaStoreExport(
+          clientId,
+          'https://ppf3l3mxc2lorh5hkrsj6zwyim0bupxw.lambda-url.ap-south-1.on.aws/',
+          'VMS',
+      );
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    if ( product === 'runai' ) {
+      const exportData = await lambdaStoreExport(
+          clientId,
+          'https://mdm3mf7wuficgv3jjspkws2nu40azlsc.lambda-url.ap-south-1.on.aws/',
+          'Run AI',
+      );
+      console.log( '🚀 ~ additionalProductExport ~ exportData:', exportData );
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    if ( product === 'remoteoptum' ) {
+      // Detailed optom-audit export from the remote_optom_steps_summary index
+      // for the given date (passed from the UI, defaults to today). Each record
+      // is one row; the nested `steps` object is flattened into TRUE/FALSE
+      // columns in a fixed (alphabetical) order.
+      const STEP_COLUMNS = [
+        'Adjust-Phoropter', 'DuoChrome-Test', 'Explanation', 'Final-Prescription',
+        'Handover', 'History-Taking', 'JCC', 'Near-Vision', 'Personal-Intro',
+        'Subjective-Refraction', 'Trial-Frame', 'VA-Check',
+      ];
+      let optomHits = [];
+      try {
+        const osRes = await getOpenSearchData( 'remote_optom_steps_summary', {
+          // A single day is well under the 10k window; pull up to the cap.
+          // NOTE: do NOT sort on StartTime — it's an analyzed text field, and
+          // sorting on it makes OpenSearch return ZERO hits. The day filter is
+          // enough; rows come back in index order.
+          size: 10000,
+          query: { term: { 'Date': reqDate } },
+        } );
+        optomHits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
+      } catch ( osErr ) {
+        logger.error( { error: osErr, function: 'additionalProductExport.remoteOptum', clientId } );
+        return res.sendError( 'Failed to fetch Remote Optum data', 502 );
+      }
+
+      const exportData = optomHits.map( ( h ) => {
+        const s = h._source || {};
+        const steps = s.steps || {};
+        const row = {
+          'storeName': s.storeName || '',
+          'engagementId': s.engagementId || '',
+          'queue_id': s.queue_id || '',
+          'optm_name': s.optm_name || '',
+          'optm_id': s.optm_id || '',
+          'optm_Emailid': s.optm_Emailid || '',
+          'Date': s.Date || '',
+          'StartTime': s.StartTime || '',
+          'EndTime': s.EndTime || '',
+          'Duration (min)': s['Duration (min)'] != null ? s['Duration (min)'] : '',
+        };
+        for ( const col of STEP_COLUMNS ) {
+          row[col] = steps[col] === true ? 'TRUE' : 'FALSE';
+        }
+        return row;
+      } );
+
+      if ( !exportData.length ) {
+        return res.sendError( 'No data', 204 );
+      }
+      await download( exportData, res );
+      return;
+    }
+
+    return res.sendError( `Unsupported product: ${product}`, 400 );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'additionalProductExport' } );
+    return res.sendError( error, 500 );
+  }
+}

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' );
@@ -292,8 +354,11 @@ export async function createInvoice( req, res ) {
       // multi-month expansion so it's billed ONCE per invoice (not per month).
       // It's a normal line item, so it lands in the taxable subtotal below.
       try {
+        // Use the group's basepricing doc when group-wise pricing applies,
+        // else the brand-level doc.
+        const { query: oneTimeQuery } = await resolveBasePricingScope( group, getClient );
         const oneTimeBp = await basepricingService.findOne(
-            { clientId: group.clientId },
+            oneTimeQuery,
             { oneTimeFeePerStore: 1 },
         );
         const oneTimeFeePerStore = Number( oneTimeBp?.oneTimeFeePerStore ) || 0;
@@ -412,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.
@@ -425,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 ),
@@ -439,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,
       };
 
@@ -473,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' )}` ],
@@ -508,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
@@ -526,7 +639,7 @@ async function buildAnnexureRows( invoiceInfo, getgroup ) {
   // converting here would make the annexure unit price disagree with the actual
   // billed amount (e.g. a $45 negotiated price wrongly shown as $0.48).
 
-  const annexClient = await clientService.findOne( { clientId: invoiceInfo.clientId }, { 'planDetails.product': 1, 'priceType': 1 } );
+  const annexClient = await clientService.findOne( { clientId: invoiceInfo.clientId }, { 'planDetails.product': 1, 'priceType': 1, 'billingGroupWisePricing': 1 } );
   const billingTypeMap = {};
   ( annexClient?.planDetails?.product || [] ).forEach( ( p ) => {
     billingTypeMap[p.productName] = p.billingType || 'perStore';
@@ -538,7 +651,18 @@ async function buildAnnexureRows( invoiceInfo, getgroup ) {
   // appear once per tier (e.g. the same store listed at $45 and again at $40).
   // Instead we pull the tiers here and assign each store a single tier price
   // below, in JS, by its 1-based index within the product.
-  const pricingDoc = await basepricingService.findOne( { clientId: invoiceInfo.clientId }, { standard: 1, step: 1 } );
+  // Group-wise pricing: read the billing group's own doc when enabled and one
+  // exists; otherwise the brand-level doc.
+  let pricingDocQuery = { clientId: invoiceInfo.clientId, groupId: { $exists: false } };
+  if ( annexClient?.billingGroupWisePricing && getgroup?._id ) {
+    const grpDoc = await basepricingService.findOne(
+        { clientId: invoiceInfo.clientId, groupId: String( getgroup._id ) }, { _id: 1 },
+    );
+    if ( grpDoc ) {
+      pricingDocQuery = { clientId: invoiceInfo.clientId, groupId: String( getgroup._id ) };
+    }
+  }
+  const pricingDoc = await basepricingService.findOne( pricingDocQuery, { standard: 1, step: 1 } );
   const isStep = annexClient?.priceType === 'step';
   const tiersByProduct = {};
   ( ( isStep ? pricingDoc?.step : pricingDoc?.standard ) || [] ).forEach( ( p ) => {
@@ -693,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,
@@ -889,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,
@@ -1080,6 +1204,25 @@ function inWords( num ) {
 }
 
 
+// Resolve which basepricing doc applies to a billing group. When the client
+// has billingGroupWisePricing enabled AND a doc exists for this group, returns
+// that group's doc; otherwise falls back to the brand-level doc (groupId unset).
+// Returns { query, groupId } where query is the mongo filter for the chosen doc
+// and groupId is the group id to use in aggregation lookups (or null for brand).
+async function resolveBasePricingScope( group, getClient ) {
+  const brandQuery = { clientId: group.clientId, groupId: { $exists: false } };
+  if ( getClient?.billingGroupWisePricing && group?._id ) {
+    const groupIdStr = String( group._id );
+    const groupDoc = await basepricingService.findOne(
+        { clientId: group.clientId, groupId: groupIdStr }, { _id: 1 },
+    );
+    if ( groupDoc ) {
+      return { query: { clientId: group.clientId, groupId: groupIdStr }, groupId: groupIdStr };
+    }
+  }
+  return { query: brandQuery, groupId: null };
+}
+
 async function standardPrice( group, getClient, baseDate ) {
   console.log( '🚀 ~ standardPrice ~ baseDate:', baseDate.format( 'MMM YYYY' ) );
   const currentMonthDays = dayjs().daysInMonth();
@@ -1088,6 +1231,9 @@ async function standardPrice( group, getClient, baseDate ) {
   // Computed once so the aggregation pipelines can inline a $literal.
   const isFlatPricing = group.proRata === 'flat';
   console.log( '🚀 ~ standardPrice ~ isFlatPricing:', isFlatPricing );
+  // Which basepricing doc applies (group-wise vs brand-level). pricingGroupId is
+  // used in the $lookup pipeline so the join picks the right doc.
+  const { groupId: pricingGroupId } = await resolveBasePricingScope( group, getClient );
   let billingTypeMap = {};
   if ( getClient?.planDetails?.product ) {
     getClient.planDetails.product.forEach( ( p ) => {
@@ -1224,7 +1370,14 @@ async function standardPrice( group, getClient, baseDate ) {
           {
             $match: {
               $expr: {
-                $eq: [ '$clientId', '$$clientId' ],
+                $and: [
+                  { $eq: [ '$clientId', '$$clientId' ] },
+                  // Match the resolved doc: a specific group's doc when group-wise
+                  // pricing applies, else the brand-level doc (no groupId).
+                  pricingGroupId ?
+                    { $eq: [ '$groupId', pricingGroupId ] } :
+                    { $not: [ { $ifNull: [ '$groupId', false ] } ] },
+                ],
               },
             },
           },
@@ -1419,7 +1572,12 @@ async function standardPrice( group, getClient, baseDate ) {
           from: 'basepricings',
           let: { clientId: group.clientId },
           pipeline: [
-            { $match: { $expr: { $eq: [ '$clientId', '$$clientId' ] } } },
+            { $match: { $expr: { $and: [
+              { $eq: [ '$clientId', '$$clientId' ] },
+              pricingGroupId ?
+                { $eq: [ '$groupId', pricingGroupId ] } :
+                { $not: [ { $ifNull: [ '$groupId', false ] } ] },
+            ] } } },
             { $project: { standard: 1 } },
           ],
           as: 'basepricing',
@@ -1527,6 +1685,8 @@ async function stepPrice( group, getClient ) {
   // 'flat' => every store billed for full month.
   // 'prorate' => actual working days. See standardPrice for the same flag.
   const isFlatPricing = group.proRata === 'flat';
+  // Which basepricing doc applies (group-wise vs brand-level).
+  const { query: pricingDocQuery, groupId: pricingGroupId } = await resolveBasePricingScope( group, getClient );
   let billingTypeMap = {};
   if ( getClient?.planDetails?.product ) {
     getClient.planDetails.product.forEach( ( p ) => {
@@ -1628,7 +1788,12 @@ async function stepPrice( group, getClient ) {
           from: 'basepricings',
           let: { clientId: group.clientId },
           pipeline: [
-            { $match: { $expr: { $eq: [ '$clientId', '$$clientId' ] } } },
+            { $match: { $expr: { $and: [
+              { $eq: [ '$clientId', '$$clientId' ] },
+              pricingGroupId ?
+                { $eq: [ '$groupId', pricingGroupId ] } :
+                { $not: [ { $ifNull: [ '$groupId', false ] } ] },
+            ] } } },
             { $project: { step: 1 } },
           ],
           as: 'basepricing',
@@ -1637,7 +1802,7 @@ async function stepPrice( group, getClient ) {
       { $unwind: { path: '$basepricing', preserveNullAndEmptyArrays: true } },
     ] );
 
-    let stepPriceData = await basepricingService.findOne( { clientId: group.clientId } );
+    let stepPriceData = await basepricingService.findOne( pricingDocQuery );
     let pricingRanges = stepPriceData?.step || [];
     let defaultPrice = pricingRanges.length > 0 ? pricingRanges[0].negotiatePrice : 0;
 
@@ -1682,7 +1847,7 @@ async function stepPrice( group, getClient ) {
   // Drop eachStore products — those are handled by the per-store branch above.
   perStoreRows = perStoreRows.filter( ( p ) => !eachStoreProductNames.includes( p.productName ) );
 
-  const stepPriceRecord = await basepricingService.findOne( { clientId: group.clientId } );
+  const stepPriceRecord = await basepricingService.findOne( pricingDocQuery );
   // Tiers ordered by range start so per-store tier assignment walks low-to-high.
   const pricing = ( stepPriceRecord?.step || [] ).slice().sort( ( a, b ) => {
     const aStart = parseInt( String( a.storeRange || '0' ).split( '-' )[0], 10 ) || 0;
@@ -2466,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 );
     }
@@ -2496,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 ) => {
@@ -2522,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/paymentSubscription.controllers.js

@@ -85,6 +85,7 @@ export const clientBillingSubscriptionInfo = async ( req, res, next ) => {
           billingDetails: 1,
           price: 1,
           priceType: 1,
+          billingGroupWisePricing: 1,
           virtualAccount: 1,
           paymentInvoice: 1,
         },
@@ -259,6 +260,7 @@ export const clientBillingSubscriptionInfo = async ( req, res, next ) => {
     currentPlanInfo.dueLimitReached = getPI;
     currentPlanInfo.price = clientInfo[0].price || '--';
     currentPlanInfo.priceType = clientInfo[0].priceType || '--';
+    currentPlanInfo.billingGroupWisePricing = clientInfo[0].billingGroupWisePricing || false;
     currentPlanInfo.subscriptionType = clientInfo[0].planDetails.subscriptionType || '--';
     currentPlanInfo.subscriptionPeriod = clientInfo[0].planDetails.subscriptionPeriod || '--';
     currentPlanInfo.storeCount = storeCount || '--';
@@ -2246,7 +2248,15 @@ export const invoiceList = async ( req, res ) => {
 
 export const priceList = async ( req, res ) => {
   try {
-    let pricingDetails = await basePricingService.findOne( { clientId: { $exists: true }, clientId: req.body.clientId }, { standard: 1, step: 1, oneTimeFeePerStore: 1 } );
+    // Group-wise pricing: when a groupId is sent, read that group's own
+    // basepricing doc; otherwise read the brand-level doc (groupId unset).
+    const priceQuery = { clientId: req.body.clientId };
+    if ( req.body.groupId ) {
+      priceQuery.groupId = req.body.groupId;
+    } else {
+      priceQuery.groupId = { $exists: false };
+    }
+    let pricingDetails = await basePricingService.findOne( priceQuery, { standard: 1, step: 1, oneTimeFeePerStore: 1 } );
     if ( !pricingDetails ) {
       return res.sendError( 'no data found', 204 );
     }
@@ -2360,7 +2370,15 @@ export const priceList = async ( req, res ) => {
 
 export const pricingListUpdate = async ( req, res ) => {
   try {
-    let getPriceInfo = await basePricingService.findOne( { clientId: { $exists: true }, clientId: req.body.clientId }, { standard: 1, step: 1 } );
+    // Group-wise pricing: target the group's own basepricing doc when a groupId
+    // is sent; otherwise the brand-level doc (groupId unset).
+    const priceQuery = { clientId: req.body.clientId };
+    if ( req.body.groupId ) {
+      priceQuery.groupId = req.body.groupId;
+    } else {
+      priceQuery.groupId = { $exists: false };
+    }
+    let getPriceInfo = await basePricingService.findOne( priceQuery, { standard: 1, step: 1 } );
     let findClient = await paymentService.findOneClient( { clientId: req.body.clientId } );
 
     console.log( getPriceInfo );
@@ -2370,8 +2388,10 @@ export const pricingListUpdate = async ( req, res ) => {
       pricingType: findClient.priceType,
     };
 
-    if ( findClient.priceType==='standard' ) {
-      getPriceInfo.standard.map( ( item ) => {
+    // Old-data snapshot for the audit log. Guard on getPriceInfo: a brand-new
+    // billing-group doc has none yet, and the no-doc path is handled below.
+    if ( getPriceInfo && findClient.priceType==='standard' ) {
+      ( getPriceInfo.standard || [] ).map( ( item ) => {
         oldData = {
           ...oldData,
           [item.productName+' '+'negotiatePrice']: item.negotiatePrice,
@@ -2383,8 +2403,8 @@ export const pricingListUpdate = async ( req, res ) => {
           };
         }
       } );
-    } else {
-      getPriceInfo.step.map( ( item ) => {
+    } else if ( getPriceInfo ) {
+      ( getPriceInfo.step || [] ).map( ( item ) => {
         oldData = {
           ...oldData,
           [item.productName+' '+'negotiatePrice']: item.negotiatePrice,
@@ -2496,6 +2516,13 @@ export const pricingListUpdate = async ( req, res ) => {
     if ( req.body.oneTimeFeePerStore != null && req.body.oneTimeFeePerStore !== '' ) {
       getPriceInfo.oneTimeFeePerStore = Number( req.body.oneTimeFeePerStore ) || 0;
     }
+    // Keep the group identity on the doc when saving group-wise pricing.
+    if ( req.body.groupId ) {
+      getPriceInfo.groupId = req.body.groupId;
+      if ( req.body.groupName ) {
+        getPriceInfo.groupName = req.body.groupName;
+      }
+    }
     getPriceInfo.save().then( async () => {
       let clientDetails = await paymentService.findOne( { clientId: req.body.clientId }, { priceType: 1, paymentInvoice: 1, planDetails: 1 } );
       clientDetails.priceType = req.body.type;
@@ -2566,7 +2593,15 @@ export const pricingListUpdate = async ( req, res ) => {
 
 async function updatePricing( req, res, update ) {
   let baseProduct = await basePricingService.findOne( { clientId: { $exists: false } }, { basePricing: 1 } );
-  let getPriceInfo = await basePricingService.findOne( { clientId: { $exists: true }, clientId: req.body.clientId }, { standard: 1, step: 1 } );
+  // Group-wise pricing: scope the doc to the group when a groupId is sent;
+  // otherwise the brand-level doc (groupId unset).
+  const pricingDocQuery = { clientId: req.body.clientId };
+  if ( req.body.groupId ) {
+    pricingDocQuery.groupId = req.body.groupId;
+  } else {
+    pricingDocQuery.groupId = { $exists: false };
+  }
+  let getPriceInfo = await basePricingService.findOne( pricingDocQuery, { standard: 1, step: 1 } );
   let clientDetails = await paymentService.findOne( { clientId: req.body.clientId } );
   if ( clientDetails ) {
     let products = clientDetails.planDetails.product.map( ( item ) => item.productName );
@@ -2637,12 +2672,20 @@ async function updatePricing( req, res, update ) {
       step: stepList,
       clientId: req.body.clientId,
     };
+    // Stamp the group identity so group-wise pricing docs are distinguishable
+    // from the brand-level doc.
+    if ( req.body.groupId ) {
+      data.groupId = req.body.groupId;
+      if ( req.body.groupName ) {
+        data.groupName = req.body.groupName;
+      }
+    }
     console.log( '🚀 ~ updatePricing ~ data:', data );
     if ( !getPriceInfo ) {
       await basePricingService.create( data );
     } else {
       delete data.clientId;
-      await basePricingService.updateOne( { clientId: req.body.clientId }, data );
+      await basePricingService.updateOne( pricingDocQuery, data );
     }
     let product = [];
     let clientId = req.body.clientId;
@@ -4235,3 +4278,20 @@ export async function getClientDocuments( req, res ) {
   }
 }
 
+// Toggle billing-group-wise pricing on the client. When enabled, pricing is
+// maintained per billing group (separate basepricing docs keyed by groupId).
+export async function setBillingGroupWisePricing( req, res ) {
+  try {
+    const clientId = String( req.body?.clientId || '' );
+    const enabled = req.body?.enabled === true || req.body?.enabled === 'true';
+    if ( !clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+    await paymentService.updateOne( { clientId }, { billingGroupWisePricing: enabled } );
+    return res.sendSuccess( { clientId, billingGroupWisePricing: enabled } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'setBillingGroupWisePricing' } );
+    return res.sendError( error, 500 );
+  }
+}
+

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/dtos/validation.dtos.js

@@ -154,6 +154,10 @@ export const validatePriceSchema = joi.object( {
   clientId: joi.string().required(),
   products: joi.array().optional(),
   oneTimeFeePerStore: joi.number().optional().allow( null, '' ),
+  // Billing-group-wise pricing: when present, the pricing is saved to / read
+  // from the group's own basepricing doc instead of the brand-level one.
+  groupId: joi.string().optional().allow( null, '' ),
+  groupName: joi.string().optional().allow( null, '' ),
   pricing: joi.array().items( joi.object( {
     productName: joi.string().required(),
     negotiatePrice: joi.number().required(),
@@ -178,6 +182,8 @@ export const revisedParams = {
 export const validatePriceListSchema = joi.object( {
   priceType: joi.string().required(),
   clientId: joi.string().required(),
+  // Optional billing group filter for group-wise pricing.
+  groupId: joi.string().optional().allow( null, '' ),
 } );
 
 export const validatePriceListParams = {

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/routes/brandsBilling.routes.js

@@ -1,6 +1,6 @@
 
 import express from 'express';
-import { brandsBillingList, brandInvoiceList, latestDailyPricing, brandBillingGroups, updateDailyPricingWorkingDays, updateDailyPricingStoreField, getClientBillingInfo, bulkDownloadBillingGroups, bulkUpdateBillingGroups, billingSummary, additionalProducts } from '../controllers/brandsBilling.controller.js';
+import { brandsBillingList, brandInvoiceList, latestDailyPricing, brandBillingGroups, updateDailyPricingWorkingDays, updateDailyPricingStoreField, getClientBillingInfo, bulkDownloadBillingGroups, bulkUpdateBillingGroups, billingSummary, additionalProducts, additionalProductExport } from '../controllers/brandsBilling.controller.js';
 import { isAllowedSessionHandler, accessVerification } from 'tango-app-api-middleware';
 
 export const brandsBillingRouter = express.Router();
@@ -17,3 +17,4 @@ brandsBillingRouter.post( '/bulk-update-billing-groups', isAllowedSessionHandler
 brandsBillingRouter.post( '/billingSummary', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), billingSummary );
 brandsBillingRouter.get( '/billingSummary', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), billingSummary );
 brandsBillingRouter.get( '/additionalProducts', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), additionalProducts );
+brandsBillingRouter.get( '/additionalProductExport', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), additionalProductExport );

package/src/routes/paymentSubscription.routes.js

@@ -155,4 +155,7 @@ paymentSubscriptionRouter.post( '/createDefaultbillings', paymentController.crea
 paymentSubscriptionRouter.post( '/client-document/upload', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Subscription', permissions: [ 'isEdit' ] } ] } ), documentUpload.single( 'file' ), paymentController.uploadClientDocument );
 paymentSubscriptionRouter.get( '/client-document/list', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Subscription', permissions: [] } ] } ), paymentController.getClientDocuments );
 
+// Toggle billing-group-wise pricing for a client (tango only, edit perm).
+paymentSubscriptionRouter.post( '/billingGroupWisePricing', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Subscription', permissions: [ 'isEdit' ] } ] } ), paymentController.setBillingGroupWisePricing );
+
 

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 );
+};