@liiift-studio/sales-portal 2.0.0 → 2.3.0

package/api/getBalanceTransactions.js

@@ -22,22 +22,46 @@ export default async function handler(req, res) {
 		// Fetch all balance transactions for the period
 		const balanceTransactions = await fetchAllBalanceTransactions(timeRange);
 
-		// Calculate balance change from charges and refunds only (what sales data tracks)
+		// Build detailed reconciliation data
 		const RECONCILIATION_TYPES = ['charge', 'refund'];
-		let totalBalanceChange = 0;
+		let rawTotal = 0; // Accumulate as float, round once at the end
+		let chargeCount = 0;
+		let refundCount = 0;
+		let chargeTotal = 0;
+		let refundTotal = 0;
+		let settlementCurrency = null;
+		let hasCurrencyConversion = false;
+		let pendingCount = 0;
 		const flaggedTransactions = [];
 
 		balanceTransactions.forEach(transaction => {
-			if (transaction.status === 'pending') return;
+			if (!settlementCurrency && transaction.currency) {
+				settlementCurrency = transaction.currency;
+			}
+
+			if (transaction.status === 'pending') {
+				pendingCount++;
+				return;
+			}
+
+			const rate = transaction.exchange_rate || 1;
+			if (rate !== 1) hasCurrencyConversion = true;
+			const originalAmount = transaction.amount / rate;
 
 			if (RECONCILIATION_TYPES.includes(transaction.type)) {
-				totalBalanceChange += transaction.amount;
+				rawTotal += originalAmount;
+				if (transaction.type === 'charge') {
+					chargeCount++;
+					chargeTotal += originalAmount;
+				} else {
+					refundCount++;
+					refundTotal += originalAmount;
+				}
 			} else if (transaction.type !== 'payout' && transaction.type !== 'stripe_fee') {
-				// Collect disputes, adjustments, connect transfers for review
 				flaggedTransactions.push({
 					id: transaction.id,
 					type: transaction.type,
-					amount: transaction.amount,
+					amount: Math.round(originalAmount),
 					created: transaction.created,
 					description: transaction.description,
 					source: transaction.source,
@@ -45,11 +69,23 @@ export default async function handler(req, res) {
 			}
 		});
 
+		// Round the accumulated total once to minimize rounding error
+		const totalBalanceChange = Math.round(rawTotal);
+
 		return res.status(200).json({
 			success: true,
 			data: {
 				totalBalanceChange,
 				flaggedTransactions,
+				diagnostics: {
+					chargeCount,
+					refundCount,
+					chargeTotal: Math.round(chargeTotal),
+					refundTotal: Math.round(refundTotal),
+					pendingCount,
+					settlementCurrency,
+					hasCurrencyConversion,
+				},
 				transactions: balanceTransactions
 			}
 		});

package/api/utils/processors/invoiceProcessor.js

@@ -94,6 +94,7 @@ function processLineItem({ line, invoice, associatedOrder, associatedTypeface, i
 		disputeDeduction: disputeAmount || 0,
 		invoiceTotal: invoice.total_excluding_tax,
 		invoiceTotalWithTax: invoice.total,
+		chargeAmount: invoice.charge?.amount || invoice.total,
 		discountAmounts: line.discount_amounts,
 		taxAmounts: line.tax_amounts,
 		stripeFees: totalFees,
@@ -140,7 +141,8 @@ function processLineItem({ line, invoice, associatedOrder, associatedTypeface, i
 		orderNumber: associatedOrder?.orderNumber || null,
 		author: associatedTypeface?.author || null,
 		typeface: associatedTypeface || null,
-		saleType: "invoice"
+		saleType: "invoice",
+		currency: invoice.currency || 'usd'
 	};
 }
 
@@ -177,6 +179,7 @@ function processShippingCost({ invoice, associatedOrder, totalFee = null, paymen
 		disputeDeduction: disputeAmount || 0,
 		invoiceTotal: invoice.total_excluding_tax,
 		invoiceTotalWithTax: invoice.total,
+		chargeAmount: invoice.charge?.amount || invoice.total,
 		discountAmounts: null,
 		stripeFees: totalFees,
 		disputed,
@@ -230,7 +233,8 @@ function processShippingCost({ invoice, associatedOrder, totalFee = null, paymen
 		orderNumber: associatedOrder?.orderNumber || null,
 		author: null,
 		typeface: null,
-		saleType: "invoice"
+		saleType: "invoice",
+		currency: invoice.currency || 'usd'
 	};
 }
 

package/api/utils/processors/paymentProcessor.js

@@ -235,6 +235,7 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
         disputeDeduction: disputeAmount || 0,
         invoiceTotal: payment.amount,
         invoiceTotalWithTax: payment.amount,
+        chargeAmount: payment.latest_charge?.amount || payment.amount,
         discountAmounts: [],
         stripeFees: totalFees,
         disputed,
@@ -283,7 +284,8 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
         orderNumber: associatedOrder?.orderNumber || null,
         author: associatedTypeface?.author || null,
         typeface: associatedTypeface || null,
-        saleType: "paymentIntent"
+        saleType: "paymentIntent",
+        currency: payment.currency || 'usd'
     };
 }
 
@@ -319,6 +321,7 @@ function processShippingCost({ payment, associatedOrder, totalFee = null }) {
         disputeDeduction: disputeAmount || 0,
         invoiceTotal: payment.amount,
         invoiceTotalWithTax: payment.amount,
+        chargeAmount: payment.latest_charge?.amount || payment.amount,
         discountAmounts: [],
         stripeFees: totalFees,
         disputed,
@@ -359,7 +362,8 @@ function processShippingCost({ payment, associatedOrder, totalFee = null }) {
         orderNumber: associatedOrder?.orderNumber || null,
         author: null,
         typeface: null,
-        saleType: "paymentIntent"
+        saleType: "paymentIntent",
+        currency: payment.currency || 'usd'
     };
 }
 

package/components/DateRangeSalesTable.js

@@ -505,25 +505,21 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
       {/* Reconciliation Check - Only show for admin users */}
       {admin && dateRangeSales.length > 0 && (
         <Box sx={{ width: '100%', mb: 2 }}>
-          <Box 
-            sx={{ 
-              display: 'inline-block',
-              gap: 2,
-              p: 2,
-              ml: -2,
-              borderRadius: '4px',
-              border: reconciliationData.isReconciled 
-                ? '2px solid var(--green, green)' 
-                : '2px solid var(--red, red)',
-              color: reconciliationData.isReconciled
-                ? 'var(--green, green)'
-                : 'var(--red, red)',
-              backgroundColor: 'rgba(255, 255, 255, 0.9)',
-              filter: 'invert(0) !important',
-              '& *': { filter: 'invert(0) !important' },
-            }}
-          >
-            
+          <Box sx={{
+            display: 'inline-block',
+            p: 2,
+            ml: -2,
+            borderRadius: '4px',
+            border: reconciliationData.isReconciled
+              ? '2px solid var(--green, green)'
+              : '2px solid var(--red, red)',
+            color: reconciliationData.isReconciled
+              ? 'var(--green, green)'
+              : 'var(--red, red)',
+            backgroundColor: 'rgba(255, 255, 255, 0.9)',
+            filter: 'invert(0) !important',
+            '& *': { filter: 'invert(0) !important' },
+          }}>
             {reconciliationData.error ? (
               <Typography variant="body1" sx={{ color: 'var(--red, red)' }}>
                 <WarningIcon fontSize="small" sx={{ mr: 1 }} />
@@ -532,37 +528,24 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
             ) : reconciliationData.isLoading ? (
               <Typography variant="body1"><CircularProgress size={24} sx={{ mr: 1 }} /> Checking reconciliation...</Typography>
             ) : reconciliationData.isReconciled ? (
-              <Typography variant="body1" sx={{ fontWeight: 'bold'}}>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
                 <CheckCircleIcon /> Reconciled
+                {reconciliationData.percentOff !== 0 && (
+                  <span style={{ fontWeight: 'normal', opacity: 0.7 }}>
+                    ({Math.abs(reconciliationData.percentOff).toFixed(2)}% variance)
+                  </span>
+                )}
               </Typography>
             ) : (
-              <Box sx={{ display: 'flex', alignItems: 'center' }}>
-                <Tooltip title="The difference between Stripe balance change and gross sales">
-                  <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center' }}>
-                    <WarningIcon/> Needs Reconciliation (Difference: ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })})
-                  </Typography>
-                </Tooltip>
-                <Tooltip 
-                  title={
-                    <React.Fragment>
-                      <Typography variant="body2" sx={{ fontWeight: 'bold' }}>Possible causes:</Typography>
-                      <Typography variant="body2">• This could be due to a sale being refunded outside your selected date range. Check for the same difference in other periods.</Typography>
-                    </React.Fragment>
-                  }
-                  placement="right"
-                  arrow
-                >
-                  <IconButton size="small" sx={{ ml: 1, color: 'inherit' }}>
-                    <InfoIcon fontSize="small" />
-                  </IconButton>
-                </Tooltip>
-              </Box>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
+                <WarningIcon /> Needs Reconciliation — ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} off ({Math.abs(reconciliationData.percentOff).toFixed(2)}%)
+              </Typography>
             )}
-            
-            {!reconciliationData.isLoading && (
+
+            {!reconciliationData.isLoading && !reconciliationData.error && (
               <>
                 <Typography variant="body1">
-                  <strong>Stripe Balance (charges + refunds):</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Stripe Balance:</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
                 </Typography>
                 <Typography variant="body1">
                   <strong>Calculated Gross:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
@@ -570,24 +553,39 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
                     <span style={{ opacity: 0.6 }}> (incl. ${(reconciliationData.shippingTotal / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} shipping)</span>
                   )}
                 </Typography>
-              </>
-            )}
 
-            {reconciliationData.flaggedTransactions?.length > 0 && (
-              <Box sx={{ mt: 1 }}>
-                <Tooltip title="View disputes, adjustments, and other flagged transactions">
-                  <Button
-                    size="small"
-                    startIcon={<InfoIcon />}
-                    onClick={() => setFlaggedOpen(true)}
-                    sx={{ color: 'inherit', textTransform: 'none' }}
-                  >
-                    {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
-                  </Button>
-                </Tooltip>
-              </Box>
-            )}
+                {reconciliationData.checks?.length > 0 && (
+                  <Box sx={{ mt: 2, borderTop: '1px solid currentColor', pt: 1, opacity: 0.9 }}>
+                    {reconciliationData.checks.map((check, i) => (
+                      <Tooltip key={i} title={check.tip || ''} placement="right" arrow>
+                        <Typography variant="body2" sx={{
+                          display: 'flex', alignItems: 'center', gap: 0.5, py: 0.25,
+                          cursor: check.tip ? 'help' : 'default',
+                        }}>
+                          <span style={{ fontSize: '0.9em' }}>
+                            {check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : check.status === 'warn' ? '⚠' : 'ℹ'}
+                          </span>
+                          <strong>{check.label}:</strong> {check.detail}
+                        </Typography>
+                      </Tooltip>
+                    ))}
+                  </Box>
+                )}
 
+                {reconciliationData.flaggedTransactions?.length > 0 && (
+                  <Box sx={{ mt: 1 }}>
+                    <Button
+                      size="small"
+                      startIcon={<InfoIcon />}
+                      onClick={() => setFlaggedOpen(true)}
+                      sx={{ color: 'inherit', textTransform: 'none' }}
+                    >
+                      View {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
+                    </Button>
+                  </Box>
+                )}
+              </>
+            )}
           </Box>
         </Box>
       )}

package/components/LoginForm.js

@@ -1,23 +1,23 @@
-// Login form modal component for sales portal authentication
+// Login form component for sales portal authentication
 import React, { useEffect, useState } from 'react';
-import { Typography, Input, Button, Box, Dialog, DialogContent } from '@mui/material';
+import { Typography, Input, Button, Box } from '@mui/material';
 import packageJson from '../package.json';
 
 const { version } = packageJson;
 
 /**
- * LoginForm modal component for designer authentication
+ * LoginForm component for designer authentication
+ * Renders as an inline centered card (not a modal overlay) so the
+ * site header and footer remain accessible.
  * @param {Object} props Component props
- * @param {boolean} props.open Whether the modal is open
- * @param {Function} props.onClose Callback when the modal is closed
- * @param {Function} props.onLoginSuccess Callback when login succeeds, receives { designers, admin, user, password }
- * @param {Function} props.renderLoader Optional render prop for custom loader component
- * @param {string} props.apiEndpoint Optional custom API endpoint (default: '/api/sales-portal/getDesignerInfo')
- * @param {Object} props.texts Optional text customization { title, description, subtitle, buttonLabel }
+ * @param {boolean} props.open Whether the form is visible
+ * @param {Function} props.onLoginSuccess Callback when login succeeds
+ * @param {Function} props.renderLoader Optional render prop for custom loader
+ * @param {string} props.apiEndpoint Optional custom API endpoint
+ * @param {Object} props.texts Optional text customization
  */
 export default function LoginForm({
 	open = true,
-	onClose,
 	onLoginSuccess,
 	renderLoader,
 	apiEndpoint = '/api/sales-portal/getDesignerInfo',
@@ -72,7 +72,7 @@ export default function LoginForm({
 		}
 	};
 
-	// Clear message when inputs change or modal reopens
+	// Clear message when inputs change or form reopens
 	useEffect(() => {
 		setMessage('');
 	}, [password, user]);
@@ -88,32 +88,27 @@ export default function LoginForm({
 		}
 	};
 
+	if (!open) return null;
+
 	return (
-		<Dialog
-			open={open}
-			onClose={onClose}
-			maxWidth="md"
-			fullWidth
-			PaperProps={{
-				sx: {
-					borderRadius: '12px',
-					overflow: 'hidden',
-					m: { xs: 2, sm: 4 },
-					maxHeight: 'calc(100vh - 64px)',
-				}
-			}}
-			slotProps={{
-				backdrop: {
-					sx: {
-						backgroundColor: 'rgba(0, 0, 0, 0.7)',
-						backdropFilter: 'blur(4px)',
-					}
-				}
-			}}
-		>
+		<Box sx={{
+			display: 'flex',
+			justifyContent: 'center',
+			alignItems: 'center',
+			minHeight: 'calc(100vh - var(--headerHeight, 80px))',
+			px: { xs: 2, sm: 4 },
+			py: { xs: 4, sm: 8 },
+		}}>
 			{loading && renderLoader && renderLoader({ fill: true, position: 'fixed', height: '100%' })}
 
-			<DialogContent sx={{ p: 0 }}>
+			<Box sx={{
+				width: '100%',
+				maxWidth: '860px',
+				borderRadius: '12px',
+				overflow: 'hidden',
+				boxShadow: '0 8px 32px rgba(0, 0, 0, 0.12)',
+				bgcolor: 'var(--white, white)',
+			}}>
 				<Box sx={{
 					display: 'flex',
 					flexDirection: { xs: 'column', sm: 'row' },
@@ -256,7 +251,7 @@ export default function LoginForm({
 						</Box>
 					</Box>
 				</Box>
-			</DialogContent>
-		</Dialog>
+			</Box>
+		</Box>
 	);
 }

package/components/Sales.js

@@ -15,6 +15,7 @@ import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc';
 import { processChartData, processTypefaceData, processDesignersData, generateSeriesData, processLicenseTypeData } from '../utils/salesDataProcessing';
 import countryCodes from '../data/countryCode.json';
+import { getCurrencySymbol, getCurrencyLabel } from '../utils/currencyUtils';
 import { SalesTable } from './SalesTable';
 import { DateRangeSalesTable } from './DateRangeSalesTable';
 import SalesChart from './SalesChart';
@@ -522,7 +523,7 @@ export default function Sales(props) {
 							padding: "5px 10px 0 10px",
 						}}
 					>
-						{sales ? <Box component="span" sx={{ fontVariationSettings: '"wght" 300' }}><Box component="span" sx={{ display: { xs: 'none', md: 'inherit' }, opacity: "0.5" }}>USD</Box>$ </Box> : ``}
+						{sales ? <Box component="span" sx={{ fontVariationSettings: '"wght" 300' }}><Box component="span" sx={{ display: { xs: 'none', md: 'inherit' }, opacity: "0.5" }}>{getCurrencyLabel(sales[0]?.currency)}</Box>{getCurrencySymbol(sales[0]?.currency)} </Box> : ``}
 						{sales ? (
 							<>
 								<span className={`sales-total`} style={{ fontVariationSettings: '"wght" 900' }}>

package/components/SalesPortalPage.js

@@ -67,7 +67,7 @@ export default function SalesPortalPage({
 	const isLoggedIn = !!designers;
 
 	const content = (
-		<Box sx={{ minHeight: '100vh' }}>
+		<Box sx={{ minHeight: 'calc(100vh - var(--headerHeight, 80px))' }}>
 			{/* Login Modal */}
 			<LoginForm
 				open={!isLoggedIn}

package/components/SalesTable.js

@@ -162,58 +162,41 @@ export function SalesTable({ sales = [], designer = {}, admin = false, loading =
       sx={{ display: 'flex', flexWrap: 'wrap', width: '100%' }}
     >
       {/* Reconciliation Check - Only show for admin users */}
-      {admin && !reconciliationData.error && sales.length > 0 &&  (
+      {admin && !reconciliationData.error && sales.length > 0 && (
         <Box sx={{ width: '100%', mb: 2 }}>
-          <Box 
-            sx={{ 
-              display: 'inline-block',
-              gap: 2,
-              p: 2,
-              mt: "20px",
-              borderRadius: '4px',
-              border: reconciliationData.isReconciled 
-                ? '2px solid var(--green, green)' 
-                : '2px solid var(--red, red)',
-              color: reconciliationData.isReconciled
-                ? 'var(--green, green)'
-                : 'var(--red, red)',
-            }}
-          >
+          <Box sx={{
+            display: 'inline-block',
+            p: 2,
+            mt: '20px',
+            borderRadius: '4px',
+            border: reconciliationData.isReconciled
+              ? '2px solid var(--green, green)'
+              : '2px solid var(--red, red)',
+            color: reconciliationData.isReconciled
+              ? 'var(--green, green)'
+              : 'var(--red, red)',
+          }}>
             {reconciliationData.isLoading ? (
               <Typography variant="body1"><CircularProgress size={24} /> Checking reconciliation...</Typography>
             ) : reconciliationData.isReconciled ? (
-              <Typography variant="body1" sx={{ fontWeight: 'bold' }}>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
                 <CheckCircleIcon /> Reconciled
+                {reconciliationData.percentOff !== 0 && (
+                  <span style={{ fontWeight: 'normal', opacity: 0.7 }}>
+                    ({Math.abs(reconciliationData.percentOff).toFixed(2)}% variance)
+                  </span>
+                )}
               </Typography>
             ) : (
-              <Box sx={{ display: 'flex', alignItems: 'center' }}>
-                <Tooltip title="The difference between Stripe balance change and gross sales">
-                  <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center' }}>
-                    <WarningIcon/> Needs Reconciliation (Difference: ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })})
-                  </Typography>
-                </Tooltip>
-                <Tooltip 
-                  title={
-                    <React.Fragment>
-                      <Typography variant="body2" sx={{ fontWeight: 'bold' }}>Possible causes:</Typography>
-                      <Typography variant="body2">• This could be due to a sale being refunded in another month. Check for the same difference either the prior or next month.</Typography>
-                      <Typography variant="body2">• If a payment was approved after the invoice was finalized, there might be a delayed payment that shows up next month.</Typography>
-                    </React.Fragment>
-                  }
-                  placement="right"
-                  arrow
-                >
-                  <IconButton size="small" sx={{ ml: 1, color: 'inherit' }}>
-                    <InfoIcon fontSize="small" />
-                  </IconButton>
-                </Tooltip>
-              </Box>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
+                <WarningIcon /> Needs Reconciliation — ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} off ({Math.abs(reconciliationData.percentOff).toFixed(2)}%)
+              </Typography>
             )}
-            
+
             {!reconciliationData.isLoading && (
               <>
                 <Typography variant="body1">
-                  <strong>Stripe Balance (charges + refunds):</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Stripe Balance:</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
                 </Typography>
                 <Typography variant="body1">
                   <strong>Calculated Gross:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
@@ -221,24 +204,40 @@ export function SalesTable({ sales = [], designer = {}, admin = false, loading =
                     <span style={{ opacity: 0.6 }}> (incl. ${(reconciliationData.shippingTotal / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} shipping)</span>
                   )}
                 </Typography>
-              </>
-            )}
 
-            {reconciliationData.flaggedTransactions?.length > 0 && (
-              <Box sx={{ mt: 1 }}>
-                <Tooltip title="View disputes, adjustments, and other flagged transactions">
-                  <Button
-                    size="small"
-                    startIcon={<InfoIcon />}
-                    onClick={() => setFlaggedOpen(true)}
-                    sx={{ color: 'inherit', textTransform: 'none' }}
-                  >
-                    {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
-                  </Button>
-                </Tooltip>
-              </Box>
-            )}
+                {/* Diagnostic checks */}
+                {reconciliationData.checks?.length > 0 && (
+                  <Box sx={{ mt: 2, borderTop: '1px solid currentColor', pt: 1, opacity: 0.9 }}>
+                    {reconciliationData.checks.map((check, i) => (
+                      <Tooltip key={i} title={check.tip || ''} placement="right" arrow>
+                        <Typography variant="body2" sx={{
+                          display: 'flex', alignItems: 'center', gap: 0.5, py: 0.25,
+                          cursor: check.tip ? 'help' : 'default',
+                        }}>
+                          <span style={{ fontSize: '0.9em' }}>
+                            {check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : check.status === 'warn' ? '⚠' : 'ℹ'}
+                          </span>
+                          <strong>{check.label}:</strong> {check.detail}
+                        </Typography>
+                      </Tooltip>
+                    ))}
+                  </Box>
+                )}
 
+                {reconciliationData.flaggedTransactions?.length > 0 && (
+                  <Box sx={{ mt: 1 }}>
+                    <Button
+                      size="small"
+                      startIcon={<InfoIcon />}
+                      onClick={() => setFlaggedOpen(true)}
+                      sx={{ color: 'inherit', textTransform: 'none' }}
+                    >
+                      View {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
+                    </Button>
+                  </Box>
+                )}
+              </>
+            )}
           </Box>
         </Box>
       )}

package/hooks/__tests__/useReconciliation.test.js

@@ -11,16 +11,17 @@ import {
 } from '../../__fixtures__/sampleSales.js';
 
 describe('calculateGrossSales', () => {
-	test('simple sale: grossSales equals totalWithTax', () => {
+	test('simple sale: grossSales equals chargeAmount', () => {
 		const { grossSales, shippingTotal } = calculateGrossSales([simpleSale]);
 
-		expect(grossSales).toBe(5350);
+		expect(grossSales).toBe(5350); // chargeAmount
 		expect(shippingTotal).toBe(0);
 	});
 
 	test('shipping is included in gross but tracked separately', () => {
 		const { grossSales, shippingTotal } = calculateGrossSales([simpleSale, shippingSale]);
 
+		// Each has unique ID so both chargeAmounts are summed
 		expect(grossSales).toBe(5350 + 1605);
 		expect(shippingTotal).toBe(1605);
 	});
@@ -28,20 +29,19 @@ describe('calculateGrossSales', () => {
 	test('refund is subtracted from gross', () => {
 		const { grossSales } = calculateGrossSales([saleWithRefund]);
 
-		// totalWithTax (10700) - refund.total (10700) = 0
+		// chargeAmount (10700) - refund.total (10700) = 0
 		expect(grossSales).toBe(0);
 	});
 
-	test('multi-line invoice refund is deduplicated by ID', () => {
+	test('multi-line invoice: charge counted once, refund counted once', () => {
 		const { grossSales } = calculateGrossSales([multiLineItem1, multiLineItem2]);
 
-		// Both items have totalWithTax 5350 each = 10700
-		// Both have the SAME refund ref_multi789 with total 5000
-		// Should only subtract 5000 once, not twice
+		// Both items have the SAME id (in_multi456) — chargeAmount (10700) counted once
+		// Both have the SAME refund ref_multi789 with total 5000 — counted once
 		expect(grossSales).toBe(10700 - 5000);
 	});
 
-	test('refund without ID is still counted (fallback)', () => {
+	test('refund without ID is skipped (known limitation)', () => {
 		const saleWithUnidentifiedRefund = {
 			...simpleSale,
 			refunds: [{
@@ -52,20 +52,17 @@ describe('calculateGrossSales', () => {
 		};
 
 		const { grossSales } = calculateGrossSales([saleWithUnidentifiedRefund]);
-		// Refund without id is skipped by dedup logic (refund.id is falsy)
-		// So it won't be subtracted — this is a known limitation
 		expect(grossSales).toBe(5350);
 	});
 
 	test('disputed sale: disputeDeduction is NOT subtracted from grossSales', () => {
 		const { grossSales } = calculateGrossSales([disputedSale]);
 
-		// totalWithTax is 21400, disputeDeduction is stored separately
-		// grossSales should be the full 21400
+		// chargeAmount is 21400, disputeDeduction is stored separately
 		expect(grossSales).toBe(21400);
 	});
 
-	test('payment intent sale works the same as invoice', () => {
+	test('payment intent sale uses chargeAmount', () => {
 		const { grossSales } = calculateGrossSales([paymentIntentSale]);
 
 		expect(grossSales).toBe(8000);
@@ -80,12 +77,20 @@ describe('calculateGrossSales', () => {
 
 	test('mixed sales: products + shipping + refund', () => {
 		const { grossSales, shippingTotal } = calculateGrossSales([
-			simpleSale,       // 5350
-			shippingSale,     // 1605
-			saleWithRefund,   // 10700 - 10700 refund = 0
+			simpleSale,       // chargeAmount 5350, unique ID
+			shippingSale,     // chargeAmount 1605, unique ID
+			saleWithRefund,   // chargeAmount 10700 - refund 10700 = 0, unique ID
 		]);
 
 		expect(grossSales).toBe(5350 + 1605 + 10700 - 10700);
 		expect(shippingTotal).toBe(1605);
 	});
+
+	test('duplicate IDs only counted once for charge', () => {
+		const dup1 = { ...simpleSale, id: 'in_dup', chargeAmount: 5000 };
+		const dup2 = { ...simpleSale, id: 'in_dup', chargeAmount: 5000 };
+
+		const { grossSales } = calculateGrossSales([dup1, dup2]);
+		expect(grossSales).toBe(5000); // Not 10000
+	});
 });

package/hooks/calculateGrossSales.js

@@ -1,24 +1,32 @@
 // Pure function for calculating gross sales — extracted for testability
 /**
- * Calculates gross sales from sales data, matching Stripe's charge+refund total
+ * Calculates gross sales matching Stripe's charge+refund balance.
+ * Uses chargeAmount (actual amount Stripe charged the customer, including tax)
+ * deduplicated by invoice/payment ID so multi-line invoices are counted once.
  * @param {Array} sales - Array of sale objects
  * @returns {Object} grossSales total and shipping breakdown (in cents)
  */
 export function calculateGrossSales(sales) {
 	let grossSales = 0;
 	let shippingTotal = 0;
+	const processedCharges = new Set();
 	const processedRefunds = new Set();
 
 	sales.forEach(sale => {
-		// Use totalWithTax for all items — this is what Stripe actually charged
-		grossSales += sale?.totalWithTax || 0;
+		const chargeId = sale?.id;
+
+		// Use chargeAmount (actual Stripe charge including tax) per unique charge
+		// Fall back to totalWithTax for backward compatibility
+		if (chargeId && !processedCharges.has(chargeId)) {
+			processedCharges.add(chargeId);
+			grossSales += sale?.chargeAmount || sale?.invoiceTotalWithTax || 0;
+		}
 
 		if (sale?.shippingProvision) {
 			shippingTotal += sale?.totalWithTax || 0;
 		}
 
 		// Deduplicate refunds by ID — multi-line invoices repeat the same refunds
-		// Use refund.total (actual Stripe amount) not adjustedTotal (proportional)
 		sale?.refunds?.forEach(refund => {
 			if (refund?.id && !processedRefunds.has(refund.id)) {
 				processedRefunds.add(refund.id);

package/hooks/useReconciliation.js

@@ -1,19 +1,97 @@
-// Shared hook for Stripe balance reconciliation
+// Shared hook for Stripe balance reconciliation with diagnostic checks
 import { useState, useEffect } from 'react';
 import { calculateGrossSales } from './calculateGrossSales.js';
 
 // Re-export for backward compatibility
 export { calculateGrossSales };
 
+/**
+ * Builds diagnostic checks comparing sales data against Stripe balance
+ * @param {Object} params - Sales and Stripe data
+ * @returns {Array} Array of check results
+ */
+function buildChecks({ sales, diagnostics, grossSales, totalBalanceChange, difference, flaggedTransactions }) {
+	const checks = [];
+	const uniqueChargeIds = new Set(sales.map(s => s.id)).size;
+	const salesRefundIds = new Set();
+	sales.forEach(s => s.refunds?.forEach(r => r.id && salesRefundIds.add(r.id)));
+	const testSales = sales.filter(s => s.testSale);
+
+	// 1. Transaction count match
+	const countMatch = uniqueChargeIds === diagnostics.chargeCount;
+	checks.push({
+		label: 'Transaction count',
+		status: countMatch ? 'pass' : 'fail',
+		detail: `${uniqueChargeIds} sales vs ${diagnostics.chargeCount} Stripe charges`,
+		tip: !countMatch ? 'Mismatch may indicate missing orders in Sanity or charges outside this period.' : null,
+	});
+
+	// 2. Refund count match
+	const refundMatch = salesRefundIds.size === diagnostics.refundCount;
+	checks.push({
+		label: 'Refund count',
+		status: diagnostics.refundCount === 0 && salesRefundIds.size === 0 ? 'pass' : refundMatch ? 'pass' : 'warn',
+		detail: `${salesRefundIds.size} in sales vs ${diagnostics.refundCount} in Stripe`,
+		tip: !refundMatch ? 'A refund may have been issued in a different month than the original charge.' : null,
+	});
+
+	// 3. Currency conversion
+	if (diagnostics.hasCurrencyConversion) {
+		const pctOff = totalBalanceChange !== 0 ? Math.abs(difference / totalBalanceChange) * 100 : 0;
+		checks.push({
+			label: 'Currency conversion',
+			status: pctOff < 1 ? 'info' : 'warn',
+			detail: `Settlement currency: ${diagnostics.settlementCurrency?.toUpperCase()}. Exchange rate rounding may cause up to ~1% variance.`,
+			tip: pctOff >= 1 ? 'Large currency variance — verify exchange rates on specific transactions in Stripe dashboard.' : null,
+		});
+	}
+
+	// 4. Amount reconciliation
+	const pctDiff = grossSales !== 0 ? (difference / grossSales) * 100 : 0;
+	checks.push({
+		label: 'Amount reconciliation',
+		status: Math.abs(difference) < 1 ? 'pass' : Math.abs(pctDiff) < 1 ? 'warn' : 'fail',
+		detail: `Difference: $${(Math.abs(difference) / 100).toFixed(2)} (${Math.abs(pctDiff).toFixed(2)}%)`,
+		tip: Math.abs(difference) >= 1 ? 'Small differences are usually exchange rate rounding. Larger gaps may indicate a charge or refund crossing a month boundary.' : null,
+	});
+
+	// 5. Pending transactions
+	if (diagnostics.pendingCount > 0) {
+		checks.push({
+			label: 'Pending transactions',
+			status: 'warn',
+			detail: `${diagnostics.pendingCount} pending balance transactions excluded`,
+			tip: 'Pending transactions haven\'t settled yet. They\'ll appear in reconciliation once settled (usually 2 business days).',
+		});
+	}
+
+	// 6. Flagged transactions
+	if (flaggedTransactions.length > 0) {
+		const totalFlagged = flaggedTransactions.reduce((sum, t) => sum + t.amount, 0);
+		checks.push({
+			label: 'Non-standard transactions',
+			status: 'info',
+			detail: `${flaggedTransactions.length} transactions ($${(Math.abs(totalFlagged) / 100).toFixed(2)}) — disputes, adjustments, or transfers`,
+			tip: 'These affect your Stripe balance but aren\'t sales or refunds. Click to review details.',
+		});
+	}
+
+	// 7. Test sales
+	if (testSales.length > 0) {
+		const testTotal = testSales.reduce((sum, s) => sum + (s.totalWithTax || 0), 0);
+		checks.push({
+			label: 'Test sales detected',
+			status: 'info',
+			detail: `${testSales.length} test transactions ($${(testTotal / 100).toFixed(2)}) from internal accounts`,
+			tip: 'Test sales are included in the totals. These come from accounts marked as test/debug.',
+		});
+	}
+
+	return checks;
+}
+
 /**
  * Hook for fetching and comparing Stripe balance transactions against sales data
- * @param {Object} options
- * @param {Object} options.designer - Designer data with user/password
- * @param {boolean} options.admin - Whether user is admin
- * @param {Array} options.sales - Sales data to reconcile against
- * @param {Date} [options.date] - Month date (for monthly view)
- * @param {Object} [options.dateRange] - Date range with start/end (for export view)
- * @returns {Object} Reconciliation state
  */
 export function useReconciliation({ designer, admin, sales, date, dateRange }) {
 	const [reconciliationData, setReconciliationData] = useState({
@@ -23,7 +101,10 @@ export function useReconciliation({ designer, admin, sales, date, dateRange }) {
 		grossSales: 0,
 		shippingTotal: 0,
 		difference: 0,
+		percentOff: 0,
 		flaggedTransactions: [],
+		checks: [],
+		diagnostics: null,
 		error: null
 	});
 
@@ -58,16 +139,31 @@ export function useReconciliation({ designer, admin, sales, date, dateRange }) {
 				if (data.success) {
 					const totalBalanceChange = data.data.totalBalanceChange;
 					const flaggedTransactions = data.data.flaggedTransactions || [];
+					const diagnostics = data.data.diagnostics || {};
 					const { grossSales, shippingTotal } = calculateGrossSales(sales);
+					const difference = totalBalanceChange - grossSales;
+					const percentOff = grossSales !== 0 ? (difference / grossSales) * 100 : 0;
+
+					const checks = buildChecks({
+						sales,
+						diagnostics,
+						grossSales,
+						totalBalanceChange,
+						difference,
+						flaggedTransactions,
+					});
 
 					setReconciliationData(prev => ({
 						...prev,
 						totalBalanceChange,
 						grossSales,
 						shippingTotal,
-						difference: totalBalanceChange - grossSales,
-						isReconciled: Math.abs(totalBalanceChange - grossSales) < 1,
+						difference,
+						percentOff,
+						isReconciled: Math.abs(difference) < 1 || Math.abs(percentOff) < 0.5,
 						flaggedTransactions,
+						checks,
+						diagnostics,
 						isLoading: false
 					}));
 				} else {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liiift-studio/sales-portal",
-	"version": "2.0.0",
+	"version": "2.3.0",
 	"description": "Centralized sales portal package for Liiift Studio projects",
 	"main": "index.js",
 	"types": "index.d.ts",

package/utils/currencyUtils.js

@@ -3,46 +3,71 @@
  * All sales data from API is in cents, these utilities help with proper formatting
  */
 
+// Currency symbol lookup for common currencies
+const CURRENCY_SYMBOLS = {
+	usd: '$', aud: 'A$', nzd: 'NZ$', cad: 'CA$', gbp: '£', eur: '€',
+	jpy: '¥', chf: 'CHF', sek: 'kr', nok: 'kr', dkk: 'kr',
+};
+
+/**
+ * Get the display symbol for a currency code
+ * @param {string} currencyCode - ISO 4217 currency code (e.g. 'usd', 'nzd')
+ * @returns {string} Currency symbol
+ */
+export const getCurrencySymbol = (currencyCode) => {
+	return CURRENCY_SYMBOLS[currencyCode?.toLowerCase()] || currencyCode?.toUpperCase() || '$';
+};
+
 /**
- * Format currency value in USD
- * @param {number} value - Value in dollars to format as currency
+ * Get the display label for a currency code (e.g. 'USD', 'NZD')
+ * @param {string} currencyCode - ISO 4217 currency code
+ * @returns {string} Uppercase currency label
+ */
+export const getCurrencyLabel = (currencyCode) => {
+	return currencyCode?.toUpperCase() || 'USD';
+};
+
+/**
+ * Format currency value
+ * @param {number} value - Value in major units (e.g. dollars) to format
  * @param {Object} options - Formatting options
+ * @param {string} options.currency - ISO 4217 currency code (default: 'usd')
  * @param {number} options.minimumFractionDigits - Minimum fraction digits (default: 2)
  * @param {number} options.maximumFractionDigits - Maximum fraction digits (default: 2)
  * @returns {string} Formatted currency string
  */
 export const formatCurrency = (
-  value, 
-  { minimumFractionDigits = 2, maximumFractionDigits = 2 } = {}
+	value,
+	{ currency = 'usd', minimumFractionDigits = 2, maximumFractionDigits = 2 } = {}
 ) => {
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency: 'USD',
-    minimumFractionDigits,
-    maximumFractionDigits,
-  }).format(value);
+	return new Intl.NumberFormat('en-US', {
+		style: 'currency',
+		currency: currency?.toUpperCase() || 'USD',
+		minimumFractionDigits,
+		maximumFractionDigits,
+	}).format(value);
 };
 
 /**
- * Convert cents to dollars
- * @param {number} cents - Value in cents
- * @returns {number} Value in dollars
+ * Convert cents to major currency units
+ * @param {number} cents - Value in minor units (cents)
+ * @returns {number} Value in major units (dollars)
  */
 export const centsToDollars = (cents) => {
-  if (typeof cents !== 'number') {
-    return 0;
-  }
-  return cents / 100;
+	if (typeof cents !== 'number') {
+		return 0;
+	}
+	return cents / 100;
 };
 
 /**
  * Format cents as currency
- * @param {number} cents - Value in cents
- * @param {Object} options - Formatting options
+ * @param {number} cents - Value in minor units (cents)
+ * @param {Object} options - Formatting options (passed to formatCurrency)
  * @returns {string} Formatted currency string
  */
 export const formatCentsAsCurrency = (cents, options = {}) => {
-  return formatCurrency(centsToDollars(cents), options);
+	return formatCurrency(centsToDollars(cents), options);
 };
 
 /**
@@ -52,10 +77,10 @@ export const formatCentsAsCurrency = (cents, options = {}) => {
  * @returns {number|null} Percentage change or null if previous is zero
  */
 export const calculatePercentageChange = (current, previous) => {
-  if (!previous || previous === 0) {
-    return null;
-  }
-  return ((current - previous) / previous) * 100;
+	if (!previous || previous === 0) {
+		return null;
+	}
+	return ((current - previous) / previous) * 100;
 };
 
 /**
@@ -67,13 +92,13 @@ export const calculatePercentageChange = (current, previous) => {
  * @returns {string} Formatted percentage string
  */
 export const formatPercentage = (
-  value, 
-  { decimals = 1, showPlusSign = true } = {}
+	value,
+	{ decimals = 1, showPlusSign = true } = {}
 ) => {
-  if (value === null || value === undefined) {
-    return '';
-  }
-  
-  const sign = value > 0 && showPlusSign ? '+' : '';
-  return `${sign}${value.toFixed(decimals)}%`;
+	if (value === null || value === undefined) {
+		return '';
+	}
+
+	const sign = value > 0 && showPlusSign ? '+' : '';
+	return `${sign}${value.toFixed(decimals)}%`;
 };