+
+ {/*
+ above the tabs) so it reads as a sibling of the customer
+ invoice cards — same `rounded-xl border bg-card shadow-sm
+ border-l-4` shape, with an `info` accent on the left border
+ to keep it visually distinct from order-coloured cards.
+ */}
);
}
diff --git a/src/app/api/v1/delivery-notes/[id]/invoice/route.ts b/src/app/api/v1/delivery-notes/[id]/invoice/route.ts
index 086f33c..fcc7478 100644
--- a/src/app/api/v1/delivery-notes/[id]/invoice/route.ts
+++ b/src/app/api/v1/delivery-notes/[id]/invoice/route.ts
@@ -4,6 +4,9 @@ import {
markDeliveryNoteCompletedByInvoice,
type MarkDeliveryNoteCompletedByInvoiceInput,
} from "@/lib/server/delivery-notes-service";
+import {
+ reconcileOrderItemInvoicedStatus,
+} from "@/lib/server/orders-service";
import {
buildQbInvoicePayload,
type InvoiceLineOverride,
@@ -151,18 +154,23 @@ export async function POST(
}
// Shape raw order_items into the InvoicingRow the builder expects.
- // `orderQty` is the customer-facing quantity (the order's qty,
- // not the supplier-collected qty) — matches the Invoicing page's
- // `resolveInvoiceLineDefaults` precedence.
+ // `quantity` is what the customer ordered — the invoice qty is
+ // capped at `min(qty_collected, quantity)` per
+ // `resolveInvoiceLineDefaults` so a short pickup is never
+ // over-billed. See view-model.ts for the rationale and the
+ // matching Invoicing-page UI.
const rows: InvoicingRow[] = items.map((it) => ({
id: it.id,
description: it.description,
+ quantity: typeof it.quantity === "number" ? it.quantity : null,
orderQty:
typeof it.quantity === "number"
? it.quantity
: typeof it.qty_collected === "number"
? it.qty_collected
: 1,
+ qtyCollected:
+ typeof it.qty_collected === "number" ? it.qty_collected : null,
sellingPrice:
typeof it.selling_price === "number" ? it.selling_price : 0,
companyName: dn.expand?.company?.company ?? dn.expand?.order?.company,
@@ -180,6 +188,32 @@ export async function POST(
sentByName: body.sentByName ?? "",
});
+ // Snapshot the per-row qty we'll bill on this invoice so the
+ // post-webhook reconcile can stamp `qty_invoiced` and decide
+ // `item_status` per row (see below). Without this snapshot, a
+ // short-pickup row would be left at `item_status="invoiced"`
+ // even though only part of its order qty was billed — that's the
+ // bug that caused Kusasalethu PO 390588's INV10924 to orphan the
+ // remaining 5 units with no follow-up signal in PB.
+ //
+ // The billed qty comes straight from the payload's QB invoice
+ // line (which honours `resolveInvoiceLineDefaults` + any
+ // `lineOverrides`), so what we stamp on PB matches what QB sees
+ // — no chance of drift between the two systems.
+ const billedQtyByRowId = new Map();
+ for (const line of payload.items) {
+ const matchedRow = rows.find((row) => (row.description ?? "(no description)") === line.name);
+ if (matchedRow) billedQtyByRowId.set(matchedRow.id, line.qty);
+ }
+ // Rows excluded from the bill (`excludeFromInvoice=true`) ride
+ // along for the n8n status flip but contribute 0 to the billed
+ // totals. Snap those too so reconcile's `qty_invoiced += 0` is a
+ // no-op for them.
+ const rowsBilled = payload.order_item_ids.map((id) => ({
+ id,
+ qtyJustInvoiced: billedQtyByRowId.get(id) ?? 0,
+ }));
+
const webhook = process.env.NEXT_PUBLIC_QB_INVOICE_WEBHOOK_URL ?? "";
if (!webhook) {
return NextResponse.json(
@@ -222,6 +256,32 @@ export async function POST(
webhookBody.id ??
`QB-${dn.expand.order.order_number}-${new Date().toISOString()}`;
+ // Reconcile PB's per-row invoiced-state against what we actually
+ // just billed on the QB invoice. n8n's "Build PocketBase Invoice
+ // Update" node unconditionally flips `item_status` to "invoiced"
+ // — for a short pickup that would orphan the remaining units
+ // (Kusasalethu PO 390588 / INV10924 lost 5 units this way). The
+ // helper stamps `qty_invoiced`, the invoice number, the invoice
+ // date, and the right `item_status` per row based on whether the
+ // row is now fully billed or still partially open.
+ //
+ // Failures here are non-fatal — the QB invoice exists, and the
+ // worst case is the row state being slightly stale until the
+ // next pass. Surface a console error so ops can see it in
+ // production logs and re-run if needed.
+ try {
+ await reconcileOrderItemInvoicedStatus({
+ rows: rowsBilled,
+ customerInvoiceNumber: invoiceNumber,
+ invoiceDate: new Date().toISOString().slice(0, 10),
+ });
+ } catch (reconcileErr) {
+ console.error(
+ `[POST /api/v1/delivery-notes/[id]/invoice] reconcileOrderItemInvoicedStatus failed for DN ${id} (invoice ${invoiceNumber}):`,
+ reconcileErr,
+ );
+ }
+
const closeInput: MarkDeliveryNoteCompletedByInvoiceInput = {
invoiceNumber,
sentByName: body.sentByName ?? null,
diff --git a/src/app/api/v1/order-items/[id]/split/route.ts b/src/app/api/v1/order-items/[id]/split/route.ts
index 967a3a2..d733641 100644
--- a/src/app/api/v1/order-items/[id]/split/route.ts
+++ b/src/app/api/v1/order-items/[id]/split/route.ts
@@ -16,6 +16,17 @@ import {
* The original line keeps its `order_qty` — that is exactly what the
* first supplier's PO prints. Only the new remainder line is written.
*
+ * Body (optional):
+ * `{ excludeFromInvoice?: boolean }`
+ * When true, stamps `exclude_from_invoice: true` on the remainder
+ * so the new line rides along for PO / driver / collection but
+ * never appears on the customer invoice or delivery note. Use
+ * this when the original customer line was a "kit" (e.g. "M20
+ * bolt comes with nut and washer") and the operator is splitting
+ * it across multiple suppliers — only one supplier's remainder
+ * is the customer's billable line. The default is false so the
+ * pre-existing behaviour is preserved.
+ *
* Validation (mirrors the split button's visibility rules):
* - the item must exist and be `pending` or `processed` (editable)
* - `order_qty` must be > 0 (a zero/blank order_qty means no split)
@@ -37,14 +48,38 @@ import {
export const runtime = "nodejs";
export const dynamic = "force-dynamic";
+interface SplitRequestBody {
+ excludeFromInvoice?: unknown;
+}
+
+function parseBody(value: unknown): { excludeFromInvoice: boolean } {
+ if (!value || typeof value !== "object") return { excludeFromInvoice: false };
+ const raw = value as SplitRequestBody;
+ return {
+ excludeFromInvoice: raw.excludeFromInvoice === true,
+ };
+}
+
export async function POST(
- _req: NextRequest,
+ req: NextRequest,
{ params }: { params: Promise<{ id: string }> },
) {
const { id: itemId } = await params;
+ let body: { excludeFromInvoice: boolean } = { excludeFromInvoice: false };
try {
- const result = await splitOrderItemRemainder(itemId);
+ const raw = (await req.json().catch(() => ({}))) as unknown;
+ body = parseBody(raw);
+ } catch {
+ // Treat malformed body as "no flags" — a stale UI might POST
+ // without a body, and the legacy split behaviour (no flag) is
+ // the safe default.
+ }
+
+ try {
+ const result = await splitOrderItemRemainder(itemId, {
+ excludeFromInvoice: body.excludeFromInvoice,
+ });
return NextResponse.json(result, { status: 201 });
} catch (err) {
if (err instanceof OrderItemSplitError) {
diff --git a/src/app/api/v1/orders/reconcile-invoice/route.ts b/src/app/api/v1/orders/reconcile-invoice/route.ts
new file mode 100644
index 0000000..63eb72a
--- /dev/null
+++ b/src/app/api/v1/orders/reconcile-invoice/route.ts
@@ -0,0 +1,86 @@
+import { NextRequest, NextResponse } from "next/server";
+import { assertAgentAuth } from "@/lib/server/agent-auth";
+import {
+ reconcileOrderItemInvoicedStatus,
+ type ReconcileOrderItemInvoicedInput,
+} from "@/lib/server/orders-service";
+
+/**
+ * POST /api/v1/orders/reconcile-invoice
+ *
+ * Thin wrapper around `reconcileOrderItemInvoicedStatus` from the
+ * orders-service layer. The caller — typically the Invoicing page
+ * after its QB webhook returns 2xx — passes the per-row billed qty
+ * plus the customer invoice number + date so the helper can update
+ * `qty_invoiced`, the invoice stamps, and the lifecycle status in
+ * one pass.
+ *
+ * Why this exists as a route: the bulk Invoicing page posts the QB
+ * webhook directly from the browser, so it can't import server-side
+ * helpers. This route exposes just enough surface to do the reconcile
+ * without leaking any other write capability.
+ *
+ * Auth: bearer AGENT_API_KEY (matches the rest of `/api/v1/*`).
+ */
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+interface Body {
+ rows: Array<{ id: string; qtyJustInvoiced: number }>;
+ customerInvoiceNumber: string;
+ invoiceDate: string;
+}
+
+function isBody(value: unknown): value is Body {
+ if (!value || typeof value !== "object") return false;
+ const candidate = value as Record;
+ if (!Array.isArray(candidate.rows)) return false;
+ if (typeof candidate.customerInvoiceNumber !== "string") return false;
+ if (typeof candidate.invoiceDate !== "string") return false;
+ return candidate.rows.every(
+ (row) =>
+ row &&
+ typeof row === "object" &&
+ typeof (row as Record).id === "string" &&
+ typeof (row as Record).qtyJustInvoiced === "number" &&
+ Number.isFinite((row as Record).qtyJustInvoiced as number),
+ );
+}
+
+export async function POST(request: NextRequest) {
+ try {
+ assertAgentAuth(request);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : "Unauthorized";
+ const status = (err as Error & { status?: number }).status || 401;
+ return NextResponse.json({ error: message }, { status });
+ }
+
+ let raw: unknown;
+ try {
+ raw = await request.json();
+ } catch {
+ return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+ }
+ if (!isBody(raw)) {
+ return NextResponse.json(
+ {
+ error:
+ "Body must be { rows: [{id, qtyJustInvoiced}], customerInvoiceNumber, invoiceDate }.",
+ },
+ { status: 400 },
+ );
+ }
+
+ const input: ReconcileOrderItemInvoicedInput = {
+ rows: raw.rows.map((row) => ({
+ id: row.id,
+ qtyJustInvoiced: Math.max(0, row.qtyJustInvoiced),
+ })),
+ customerInvoiceNumber: raw.customerInvoiceNumber,
+ invoiceDate: raw.invoiceDate,
+ };
+
+ const result = await reconcileOrderItemInvoicedStatus(input);
+ return NextResponse.json(result);
+}
\ No newline at end of file
diff --git a/src/components/ui/split-remainder-dialog.tsx b/src/components/ui/split-remainder-dialog.tsx
new file mode 100644
index 0000000..799a4b3
--- /dev/null
+++ b/src/components/ui/split-remainder-dialog.tsx
@@ -0,0 +1,155 @@
+import { useState } from "react";
+import { Loader2 } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+
+/**
+ * Split remainder Dialog.
+ *
+ * The "split" action on the order process page splits an
+ * under-fulfilled line into:
+ * - the original line (unchanged — the supplier's PO uses its
+ * current `order_qty`)
+ * - a new remainder line (no supplier, `quantity` = the
+ * shortfall) that the operator routes to another supplier.
+ *
+ * Often the remainder is a *different physical product* — for
+ * example the customer ordered "M20 bolt comes with nut and
+ * washer" as one line and the operator splits it across three
+ * suppliers. Only one of those three order_items is the customer's
+ * billable line; the other two are *supplier-side components* of
+ * the original kit. Without a flag, all three end up on the
+ * customer's invoice and the invoicing operator can't tell which is
+ * the kit and which are the components.
+ *
+ * The "Supplier-side component" checkbox flips `exclude_from_invoice`
+ * to `true` on the new remainder. The line still gets a PO, driver,
+ * collection — it just never reaches the customer's invoice or
+ * delivery note. Default false keeps the historical split behaviour
+ * for the short-pickup case where the remainder IS billable.
+ *
+ * Usage:
+ * { ... } }
+ * />
+ */
+export interface SplitRemainderDialogProps {
+ open: boolean;
+ /** Short label for the original line (used in the title). */
+ itemLabel: string;
+ /** The quantity that will be split off as the remainder. */
+ shortfall: number;
+ busy?: boolean;
+ serverError?: string | null;
+ onOpenChange: (open: boolean) => void;
+ /** Called with the operator's checkbox value when they confirm. */
+ onSubmit: (excludeFromInvoice: boolean) => void;
+}
+
+export function SplitRemainderDialog({
+ open,
+ itemLabel,
+ shortfall,
+ busy = false,
+ serverError = null,
+ onOpenChange,
+ onSubmit,
+}: SplitRemainderDialogProps) {
+ // Default off — the supplier-side flag is an explicit opt-in for
+ // kit-style splits, not the default short-pickup case. The modal
+ // copy explains when to tick it so the operator doesn't have to
+ // guess.
+ const [excludeFromInvoice, setExcludeFromInvoice] = useState(false);
+
+ return (
+
+ );
+}
\ No newline at end of file
diff --git a/src/lib/server/order-items-service.test.ts b/src/lib/server/order-items-service.test.ts
index df2dc8d..c0cdc21 100644
--- a/src/lib/server/order-items-service.test.ts
+++ b/src/lib/server/order-items-service.test.ts
@@ -267,6 +267,54 @@ describe("splitOrderItemRemainder", () => {
const payload = create.mock.calls[0][0] as Record;
expect(payload.category).toBe("cat-fasteners");
});
+
+ describe("excludeFromInvoice flag (supplier-side kit splits)", () => {
+ it("does NOT set exclude_from_invoice by default (legacy short-pickup behaviour)", async () => {
+ const { admin, create } = makeAdmin();
+ vi.mocked(getAdminPocketBase).mockResolvedValue(admin as never);
+
+ await splitOrderItemRemainder("item-1");
+
+ const payload = create.mock.calls[0][0] as Record;
+ expect(payload.exclude_from_invoice).toBe(false);
+ });
+
+ it("stamps exclude_from_invoice: true when the operator ticks the supplier-side checkbox", async () => {
+ const { admin, create } = makeAdmin();
+ vi.mocked(getAdminPocketBase).mockResolvedValue(admin as never);
+
+ await splitOrderItemRemainder("item-1", { excludeFromInvoice: true });
+
+ const payload = create.mock.calls[0][0] as Record;
+ expect(payload.exclude_from_invoice).toBe(true);
+ });
+
+ it("records the supplier-side flag in the split audit blob", async () => {
+ const { admin, create } = makeAdmin();
+ vi.mocked(getAdminPocketBase).mockResolvedValue(admin as never);
+
+ await splitOrderItemRemainder("item-1", { excludeFromInvoice: true });
+
+ const payload = create.mock.calls[0][0] as Record;
+ const details = JSON.parse(String(payload.order_item_details)) as {
+ split: { excludeFromInvoice?: boolean };
+ };
+ expect(details.split.excludeFromInvoice).toBe(true);
+ });
+
+ it("omits the audit flag when the operator doesn't tick the checkbox", async () => {
+ const { admin, create } = makeAdmin();
+ vi.mocked(getAdminPocketBase).mockResolvedValue(admin as never);
+
+ await splitOrderItemRemainder("item-1", { excludeFromInvoice: false });
+
+ const payload = create.mock.calls[0][0] as Record;
+ const details = JSON.parse(String(payload.order_item_details)) as {
+ split: { excludeFromInvoice?: boolean };
+ };
+ expect(details.split.excludeFromInvoice).toBe(false);
+ });
+ });
});
describe("confirmOrderItemsCollected", () => {
diff --git a/src/lib/server/order-items-service.ts b/src/lib/server/order-items-service.ts
index d28f35c..1c7e9ef 100644
--- a/src/lib/server/order-items-service.ts
+++ b/src/lib/server/order-items-service.ts
@@ -373,7 +373,27 @@ export async function confirmOrderItemsCollected(
* order_qty ≥ quantity means there is no shortfall.
* - The parent order must exist so the remainder line isn't orphaned.
*/
-export async function splitOrderItemRemainder(itemId: string): Promise<{
+/**
+ * Input shape for `splitOrderItemRemainder`. The optional
+ * `excludeFromInvoice` flag was added so the operator can mark the
+ * remainder as a "supplier-side component" of a multi-supplier
+ * customer line (e.g. "M20 bolt with nut and washer" split into 3
+ * supplier order_items — only one is the customer's billable line;
+ * the others get the supplier-side flag and never reach the
+ * customer's invoice or delivery note).
+ *
+ * The default behaviour is unchanged: a split without the flag
+ * stamps the remainder as a regular customer line (the operator can
+ * still flag it later).
+ */
+export type SplitOrderItemRemainderInput = {
+ excludeFromInvoice?: boolean;
+};
+
+export async function splitOrderItemRemainder(
+ itemId: string,
+ input: SplitOrderItemRemainderInput = {},
+): Promise<{
original: Record;
remainder: Record;
remainderQty: number;
@@ -477,6 +497,15 @@ export async function splitOrderItemRemainder(itemId: string): Promise<{
purchase_order: null,
item_status: "pending",
in_stock: !!item.in_stock,
+ // Supplier-side flag. When the operator ticks "Mark this remainder
+ // as a supplier-side component" in the split modal, the remainder
+ // rides along for PO / driver / collection but never appears on
+ // the customer invoice or delivery note. Selling price is forced
+ // to 0 so a stale quote-item view can't accidentally bill the
+ // customer for it. The flag is forwarded by the API route from
+ // the split dialog — default false keeps the old behaviour
+ // (the operator can still flip the flag later via /order-items).
+ exclude_from_invoice: input.excludeFromInvoice === true,
notes: item.notes || "",
// Split marker — lets the process page badge this line as the
// remainder of its source so splits are spottable. Stored in the
@@ -488,6 +517,11 @@ export async function splitOrderItemRemainder(itemId: string): Promise<{
at: splitAt,
remainderQty,
fromOrderQty: orderQty,
+ // Stamp the supplier-side flag into the audit trail too so
+ // a follow-up operator can see why this remainder was
+ // excluded from the customer invoice (without having to
+ // reverse-engineer the flow from the boolean column).
+ excludeFromInvoice: input.excludeFromInvoice === true,
},
}),
// Pricing audit-trail — carried over so the operator doesn't
diff --git a/src/lib/server/orders-service.test.ts b/src/lib/server/orders-service.test.ts
index bfb4059..084bb1b 100644
--- a/src/lib/server/orders-service.test.ts
+++ b/src/lib/server/orders-service.test.ts
@@ -3231,3 +3231,158 @@ describe("cancelOrderItem", () => {
expect(notes).toMatch(/cancelled by Dave/);
});
});
+
+describe("reconcileOrderItemInvoicedStatus", () => {
+ let reconcileOrderItemInvoicedStatus: typeof import("./orders-service").reconcileOrderItemInvoicedStatus;
+
+ beforeEach(async () => {
+ clearStore();
+ ({ reconcileOrderItemInvoicedStatus } = await import("./orders-service"));
+ });
+
+ it("flips a fully-invoiced row to item_status=invoiced", async () => {
+ await pbMock.collection("order_items").create({
+ id: "oi-1", order: "o-1", description: "x",
+ item_status: "ready_invoice", quantity: 10, qty_invoiced: 0,
+ });
+
+ const result = await reconcileOrderItemInvoicedStatus({
+ rows: [{ id: "oi-1", qtyJustInvoiced: 10 }],
+ customerInvoiceNumber: "INV-1",
+ invoiceDate: "2026-09-16",
+ });
+
+ const stored = (store["order_items"] as Map>).get("oi-1");
+ expect(stored?.item_status).toBe("invoiced");
+ expect(stored?.qty_invoiced).toBe(10);
+ expect(stored?.customer_invoice_number).toBe("INV-1");
+ expect(stored?.invoiced_date).toBe("2026-09-16");
+ expect(result).toMatchObject({
+ rowsInspected: 1,
+ rowsUpdated: 1,
+ rowsFullyInvoiced: 1,
+ rowsStillReady: 0,
+ });
+ });
+
+ it("flips a short-pickup row BACK to item_status=ready_invoice", async () => {
+ // The Kusasalethu case: customer ordered 10, only 8 collected,
+ // invoice was for 8. The row must stay ready so the follow-up
+ // invoice fires once the supplier delivers the remaining 2.
+ await pbMock.collection("order_items").create({
+ id: "oi-1", order: "o-1", description: "x",
+ item_status: "invoiced", // simulate n8n's unconditional flip
+ quantity: 10,
+ qty_invoiced: 0,
+ });
+
+ const result = await reconcileOrderItemInvoicedStatus({
+ rows: [{ id: "oi-1", qtyJustInvoiced: 8 }],
+ customerInvoiceNumber: "INV-1",
+ invoiceDate: "2026-09-16",
+ });
+
+ const stored = (store["order_items"] as Map>).get("oi-1");
+ expect(stored?.item_status).toBe("ready_invoice");
+ expect(stored?.qty_invoiced).toBe(8);
+ expect(stored?.customer_invoice_number).toBe("INV-1");
+ expect(stored?.invoiced_date).toBe("2026-09-16");
+ expect(result).toMatchObject({
+ rowsInspected: 1,
+ rowsUpdated: 1,
+ rowsFullyInvoiced: 0,
+ rowsStillReady: 1,
+ });
+ });
+
+ it("handles a mixed batch: one fully invoiced, one short-pickup", async () => {
+ await pbMock.collection("order_items").create({
+ id: "oi-full", order: "o-1", description: "full",
+ item_status: "invoiced", quantity: 5, qty_invoiced: 0,
+ });
+ await pbMock.collection("order_items").create({
+ id: "oi-short", order: "o-1", description: "short",
+ item_status: "invoiced", quantity: 10, qty_invoiced: 0,
+ });
+
+ const result = await reconcileOrderItemInvoicedStatus({
+ rows: [
+ { id: "oi-full", qtyJustInvoiced: 5 },
+ { id: "oi-short", qtyJustInvoiced: 7 },
+ ],
+ customerInvoiceNumber: "INV-2",
+ invoiceDate: "2026-09-17",
+ });
+
+ const full = (store["order_items"] as Map>).get("oi-full");
+ const short = (store["order_items"] as Map>).get("oi-short");
+ expect(full?.item_status).toBe("invoiced");
+ expect(full?.qty_invoiced).toBe(5);
+ expect(short?.item_status).toBe("ready_invoice");
+ expect(short?.qty_invoiced).toBe(7);
+ expect(result).toMatchObject({
+ rowsInspected: 2,
+ rowsUpdated: 2,
+ rowsFullyInvoiced: 1,
+ rowsStillReady: 1,
+ });
+ });
+
+ it("accumulates qty_invoiced across multiple invoices (follow-up invoicing)", async () => {
+ // After the partial invoice for 8 has been reconciled, the
+ // supplier delivers the remaining 2 and the follow-up invoice
+ // bills them. qty_invoiced must accumulate (8 + 2 = 10), not
+ // overwrite.
+ await pbMock.collection("order_items").create({
+ id: "oi-1", order: "o-1", description: "x",
+ item_status: "ready_invoice", quantity: 10, qty_invoiced: 8,
+ });
+
+ const result = await reconcileOrderItemInvoicedStatus({
+ rows: [{ id: "oi-1", qtyJustInvoiced: 2 }],
+ customerInvoiceNumber: "INV-2",
+ invoiceDate: "2026-09-17",
+ });
+
+ const stored = (store["order_items"] as Map>).get("oi-1");
+ expect(stored?.item_status).toBe("invoiced");
+ expect(stored?.qty_invoiced).toBe(10);
+ expect(stored?.customer_invoice_number).toBe("INV-2");
+ expect(result.rowsFullyInvoiced).toBe(1);
+ });
+
+ it("saturates qty_invoiced at quantity even if the row is over-billed", async () => {
+ // Belt-and-braces: if the caller ever passes qtyJustInvoiced that
+ // would push the total past the ordered qty (operator typo,
+ // duplicate webhook call, etc.), the helper caps at `quantity`
+ // rather than letting the row record an over-count.
+ await pbMock.collection("order_items").create({
+ id: "oi-1", order: "o-1", description: "x",
+ item_status: "ready_invoice", quantity: 10, qty_invoiced: 8,
+ });
+
+ await reconcileOrderItemInvoicedStatus({
+ rows: [{ id: "oi-1", qtyJustInvoiced: 99 }],
+ customerInvoiceNumber: "INV-3",
+ invoiceDate: "2026-09-17",
+ });
+
+ const stored = (store["order_items"] as Map>).get("oi-1");
+ expect(stored?.qty_invoiced).toBe(10);
+ expect(stored?.item_status).toBe("invoiced");
+ });
+
+ it("returns a zero-result without touching PB when given no rows", async () => {
+ const result = await reconcileOrderItemInvoicedStatus({
+ rows: [],
+ customerInvoiceNumber: "INV-1",
+ invoiceDate: "2026-09-16",
+ });
+ expect(result).toEqual({
+ rowsInspected: 0,
+ rowsUpdated: 0,
+ rowsStillReady: 0,
+ rowsFullyInvoiced: 0,
+ });
+ });
+});
diff --git a/src/lib/server/orders-service.ts b/src/lib/server/orders-service.ts
index 3df9cb9..021ac21 100644
--- a/src/lib/server/orders-service.ts
+++ b/src/lib/server/orders-service.ts
@@ -3487,6 +3487,142 @@ export interface OrderHeaderActionResult {
appliedAt: string;
}
+// ──────────────────────────────────────────────────────────────────────
+// reconcileOrderItemInvoicedStatus (post-QB-webhook reconciliation)
+// ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Per-row input for `reconcileOrderItemInvoicedStatus`. The caller
+ * (typically the DN-invoice route after a 2xx QB webhook response)
+ * passes the row id and the qty it just billed on the invoice so the
+ * helper can update `qty_invoiced`, the invoice stamps, and the
+ * lifecycle status in one pass.
+ */
+export type ReconcileOrderItemInvoicedInput = {
+ rows: Array<{ id: string; qtyJustInvoiced: number }>;
+ /**
+ * Customer-facing invoice number (e.g. "INV10924"). Stamped onto
+ * `customer_invoice_number` for every row touched by this batch.
+ */
+ customerInvoiceNumber: string;
+ /** ISO date (YYYY-MM-DD or full ISO). Stamped onto `invoiced_date`. */
+ invoiceDate: string;
+};
+
+export type ReconcileOrderItemInvoicedResult = {
+ rowsInspected: number;
+ rowsUpdated: number;
+ rowsStillReady: number;
+ rowsFullyInvoiced: number;
+};
+
+/**
+ * Reconcile `item_status` against the actual `qty_invoiced` after a
+ * QuickBooks invoice has been created for a batch of order_items.
+ *
+ * Background: the Invoicing page's `resolveInvoiceLineDefaults`
+ * caps the invoice qty at `min(qty_collected, quantity)` so a short
+ * pickup is never over-billed (the customer's mining-stores team
+ * compares the printed invoice to the goods that physically arrive,
+ * and any mismatch is a financial red flag). When the driver only
+ * collected 8 of 10 units, the QB invoice bills 8 — but the row
+ * is still partially open: the remaining 2 need to come back
+ * through the invoice flow once the supplier delivers them.
+ *
+ * n8n's "Build PocketBase Invoice Update" node unconditionally flips
+ * `item_status` to `"invoiced"` for every row in the batch. That's
+ * wrong for the partial case: it drops the row off the Invoicing
+ * tab even though 2 units are still owed. This helper runs after
+ * the QB webhook returns and walks the batch to:
+ *
+ * 1. Read the row's current `qty_invoiced` and `quantity`.
+ * 2. Add `qtyJustInvoiced` to `qty_invoiced`.
+ * 3. If `qty_invoiced >= quantity` → confirm `item_status="invoiced"`,
+ * stamp `invoiced_date` and `customer_invoice_number`.
+ * 4. If `qty_invoiced < quantity` → flip `item_status` BACK to
+ * `"ready_invoice"` so the row surfaces in the next invoicing
+ * pass, and STILL stamp `invoiced_date` / `customer_invoice_number`
+ * for audit (the partial invoice number is recorded).
+ *
+ * Idempotent: re-running the same batch on already-reconciled rows
+ * is a no-op (the qty math saturates at `quantity` and the status
+ * flip is a no-op when the target value already matches).
+ *
+ * The helper is route-agnostic — both the Invoicing page's QB
+ * modal and the DN-invoice route can call it after their webhook
+ * returns. See `src/app/api/v1/delivery-notes/[id]/invoice/route.ts`
+ * for the canonical post-webhook hook-up.
+ */
+export async function reconcileOrderItemInvoicedStatus(
+ input: ReconcileOrderItemInvoicedInput,
+): Promise {
+ if (input.rows.length === 0) {
+ return {
+ rowsInspected: 0,
+ rowsUpdated: 0,
+ rowsStillReady: 0,
+ rowsFullyInvoiced: 0,
+ };
+ }
+
+ const pb = await getAdminPocketBase();
+ pb.autoCancellation(false);
+
+ const ids = input.rows.map((r) => r.id);
+ const fetched = await pb
+ .collection(getOrderItemsCollectionName())
+ .getFullList<{
+ id: string;
+ item_status: string;
+ quantity: number | null;
+ qty_invoiced: number | null;
+ }>({
+ filter: ids.map((id) => `id = "${id.replace(/"/g, '\\"')}"`).join(" || "),
+ fields: "id,item_status,quantity,qty_invoiced",
+ batch: 500,
+ });
+
+ const byId = new Map(fetched.map((row) => [row.id, row]));
+ const invoiceDate = input.invoiceDate;
+ const customerInvoiceNumber = input.customerInvoiceNumber;
+
+ let rowsUpdated = 0;
+ let rowsStillReady = 0;
+ let rowsFullyInvoiced = 0;
+
+ for (const row of input.rows) {
+ const existing = byId.get(row.id);
+ if (!existing) continue;
+
+ const ordered = Number(existing.quantity ?? 0);
+ const previousInvoiced = Number(existing.qty_invoiced ?? 0);
+ const nextInvoiced = Math.min(ordered, previousInvoiced + row.qtyJustInvoiced);
+ const isFullyInvoiced = ordered > 0 && nextInvoiced >= ordered;
+
+ const patch: Record = {
+ qty_invoiced: nextInvoiced,
+ customer_invoice_number: customerInvoiceNumber,
+ invoiced_date: invoiceDate,
+ item_status: isFullyInvoiced ? "invoiced" : "ready_invoice",
+ };
+
+ await pb.collection(getOrderItemsCollectionName()).update(row.id, patch);
+ rowsUpdated += 1;
+ if (isFullyInvoiced) {
+ rowsFullyInvoiced += 1;
+ } else {
+ rowsStillReady += 1;
+ }
+ }
+
+ return {
+ rowsInspected: input.rows.length,
+ rowsUpdated,
+ rowsStillReady,
+ rowsFullyInvoiced,
+ };
+}
+
/**
* Mark an order as invoiced. Refuses if any line item has
* `item_status !== "invoiced"` — operator must complete invoicing
@@ -3514,9 +3650,11 @@ export async function markOrderInvoiced(orderId: string): Promise({
filter: `order = "${orderId}"`,
- fields: "id,item_status",
+ fields: "id,item_status,quantity,qty_invoiced",
batch: 1000,
});
@@ -3536,11 +3674,27 @@ export async function markOrderInvoiced(orderId: string): Promise i.item_status !== "invoiced")
- .map((i) => ({ id: i.id, reason: `item_status is "${i.item_status}", expected "invoiced"` }));
+ .map((i) => {
+ const ordered = Number(i.quantity ?? 0);
+ const billed = Number(i.qty_invoiced ?? 0);
+ const outstanding = Math.max(0, ordered - billed);
+ return outstanding > 0
+ ? {
+ id: i.id,
+ reason:
+ `Partial pickup — ${billed} of ${ordered} billed so far; ` +
+ `${outstanding} unit${outstanding === 1 ? "" : "s"} still owed. ` +
+ `A follow-up invoice will raise once the supplier delivers the rest.`,
+ }
+ : {
+ id: i.id,
+ reason: `item_status is "${i.item_status}", expected "invoiced"`,
+ };
+ });
if (uninvoiced.length > 0) {
const err = new Error(
- `Cannot mark invoiced — ${uninvoiced.length} of ${items.length} line items are not yet invoiced. ` +
+ `Cannot mark invoiced — ${uninvoiced.length} of ${items.length} line items are not yet fully invoiced. ` +
`Complete per-item invoicing first.`,
);
(err as Error & { status?: number }).status = 409;