From aa59e30ea789c243db21eb77e309e0ab96c749a8 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 26 Jun 2026 13:38:48 +0000
Subject: [PATCH 01/63] feat: setup invoice entityt

---
 .../billing/entities/invoice-line.entity.ts   | 43 ++++++++++++
 .../billing/entities/invoice.entity.ts        | 67 +++++++++++++++----
 packages/types/src/freight/index.ts           | 11 ++-
 3 files changed, 108 insertions(+), 13 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/entities/invoice-line.entity.ts

diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice-line.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice-line.entity.ts
new file mode 100644
index 000000000..a042dedb7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice-line.entity.ts
@@ -0,0 +1,43 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, JoinColumn, ManyToOne } from "typeorm";
+
+import { Invoice } from "./invoice.entity";
+
+@Entity({ schema: "freight", name: "invoice_lines" })
+export class InvoiceLine extends BaseEntity {
+  @Column({ name: "invoice_id", type: "uuid", nullable: false })
+  invoiceId!: string;
+
+  @ManyToOne(() => Invoice, { onDelete: "CASCADE" })
+  @JoinColumn({ name: "invoice_id" })
+  invoice!: Invoice;
+
+  @Column({ name: "charge_type", type: "varchar", nullable: false })
+  chargeType!: string;
+
+  @Column({ name: "description", type: "varchar", length: 255, nullable: true })
+  description?: string;
+
+  /** Units this line bills for (e.g. container count, wagon count, tons). */
+  @Column({ name: "quantity", type: "numeric", precision: 12, scale: 2, default: 1 })
+  quantity!: number;
+
+  /** Price per unit; `amount` is normally `quantity * unitRate`. */
+  @Column({ name: "unit_rate", type: "numeric", precision: 14, scale: 2, default: 0 })
+  unitRate!: number;
+
+  @Column({
+    name: "amount",
+    type: "numeric",
+    precision: 14,
+    scale: 2,
+    nullable: false,
+  })
+  amount!: number;
+
+  @Column({ name: "currency", type: "varchar", length: 8, default: "ETB" })
+  currency!: string;
+
+  @Column({ name: "metadata", type: "jsonb", nullable: true })
+  metadata?: Record<string, unknown> | null;
+}
diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
index e2a6f7cc2..61bc9c16b 100644
--- a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
@@ -1,17 +1,35 @@
 import { BaseEntity } from "@edr/api-common";
 import { Freight } from "@edr/types";
-import { Column, Entity } from "typeorm";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+import { PaymentEntity } from "../../payment/entities/payment.entity";
+import { Company } from "../../companies/entities/company.entity";
+import { CompanyProfile } from "../../companies/entities/company-profile.entity";
 
-@Entity({schema:"freight", name: "invoices" })
+@Entity({ schema: "freight", name: "invoices" })
+@Index(["companyId"])
+@Index(["companyProfileId"])
 export class Invoice extends BaseEntity {
-  @Column({ name: "booking_id", type: "uuid" })
-  bookingId!: string;
-
   @Column({ name: "invoice_number", type: "varchar", length: 64, unique: true })
   invoiceNumber!: string;
 
-  @Column({ name: "amount", type: "numeric", precision: 14, scale: 2 })
-  amount!: number;
+  /** The customer (company) this invoice is billed to. */
+  @Column({ name: "company_id", type: "uuid" })
+  companyId!: string;
+
+  @ManyToOne(() => Company)
+  @JoinColumn({ name: "company_id" })
+  company?: Company;
+
+  /** The specific company profile (importer/exporter/forwarder/...) billed. */
+  @Column({ name: "company_profile_id", type: "uuid" })
+  companyProfileId!: string;
+
+  @ManyToOne(() => CompanyProfile)
+  @JoinColumn({ name: "company_profile_id" })
+  companyProfile?: CompanyProfile;
+
+  @Column({ name: "total_amount", type: "numeric", precision: 14, scale: 2 })
+  totalAmount!: number;
 
   @Column({ name: "currency", type: "varchar", length: 8, default: "ETB" })
   currency!: string;
@@ -19,13 +37,38 @@ export class Invoice extends BaseEntity {
   @Column({
     name: "status",
     type: "enum",
-    enum: Freight.PaymentStatus,
-    default: Freight.PaymentStatus.Pending,
+    enum: Freight.InvoiceStatus,
+    default: Freight.InvoiceStatus.Draft,
   })
-  status!: Freight.PaymentStatus;
+  status!: Freight.InvoiceStatus;
 
-  @Column({ name: "issued_at", type: "timestamptz" })
-  issuedAt!: Date;
+  /** The source of the payment (e.g. booking, customer, etc.). */
+  @Column({ name: "source", type: "varchar", length: 255, nullable: false })
+  source!: string;
+
+  /** The ID of the source (e.g. booking ID, customer ID, etc.). */
+  @Column({ name: "source_id", type: "varchar", length: 255, nullable: false })
+  sourceId!: string;
+
+  /** The type of Invoice (e.g. prepaid, credit, etc.). it suppose to answer the question "what is the invoice for?" */
+  @Column({
+    type: "varchar",
+    length: 255,
+    nullable: false,
+  })
+  type!: string;
+
+  /** Set when the invoice is actually issued (DRAFT invoices leave this null). */
+  @Column({ name: "issued_at", type: "timestamptz", nullable: true })
+  issuedAt?: Date | null;
+
+  /** The ID of the payment that generated this invoice. */
+  @Column({ name: "payment_id", type: "uuid", nullable: true })
+  paymentId?: string | null;
+
+  @ManyToOne(() => PaymentEntity)
+  @JoinColumn({ name: "payment_id" })
+  payment?: PaymentEntity;
 
   @Column({ name: "due_at", type: "timestamptz" })
   dueAt!: Date;
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 412e7efa3..040848021 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -23,7 +23,7 @@ export const GOVERNMENT_PRIORITY_BONUS = 50_000;
 
 export interface GovernmentBookingFields {
   isGovernment: boolean;
-governmentInstitution?: string | null;
+  governmentInstitution?: string | null;
 }
 
 export enum ExceededAction {
@@ -128,6 +128,15 @@ export enum PaymentStatus {
   Refunded = "REFUNDED",
 }
 
+export enum InvoiceStatus {
+  Draft = "DRAFT",
+  Pending = "PENDING",
+  Paid = "PAID",
+  Overdue = "OVERDUE",
+  Cancelled = "CANCELLED",
+  Refunded = "REFUNDED",
+}
+
 export enum SchedulingStatus {
   NotScheduled = "NOT_SCHEDULED",
   Holding = "HOLDING",

From 15c37fea99388fcdf447e52f4377f4d95fa90a32 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 26 Jun 2026 13:42:48 +0000
Subject: [PATCH 02/63] chore: setup repos for invoice

---
 .../src/modules/billing/billing.module.ts         |  7 +++++--
 .../modules/billing/invoice-line.repository.ts    | 15 +++++++++++++++
 .../src/modules/billing/invoice.repository.ts     | 15 +++++++++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/invoice-line.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/invoice.repository.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 2b16b1515..1dd745088 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -4,11 +4,14 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 import { BillingController } from "./billing.controller";
 import { BillingService } from "./billing.service";
 import { Invoice } from "./entities/invoice.entity";
+import { InvoiceLine } from "./entities/invoice-line.entity";
+import { InvoiceRepository } from "./invoice.repository";
+import { InvoiceLineRepository } from "./invoice-line.repository";
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Invoice])],
+  imports: [TypeOrmModule.forFeature([Invoice, InvoiceLine])],
   controllers: [BillingController],
-  providers: [BillingService],
+  providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
   exports: [BillingService],
 })
 export class BillingModule {}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice-line.repository.ts b/apps/edr-freight-api/src/modules/billing/invoice-line.repository.ts
new file mode 100644
index 000000000..6a5482543
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice-line.repository.ts
@@ -0,0 +1,15 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+import { InvoiceLine } from "./entities/invoice-line.entity";
+
+@Injectable()
+export class InvoiceLineRepository extends BaseRepository<InvoiceLine> {
+  constructor(
+    @InjectRepository(InvoiceLine) repository: Repository<InvoiceLine>,
+  ) {
+    super(repository);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice.repository.ts b/apps/edr-freight-api/src/modules/billing/invoice.repository.ts
new file mode 100644
index 000000000..cc2e89df7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice.repository.ts
@@ -0,0 +1,15 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+import { Invoice } from "./entities/invoice.entity";
+
+@Injectable()
+export class InvoiceRepository extends BaseRepository<Invoice> {
+  constructor(
+    @InjectRepository(Invoice) repository: Repository<Invoice>,
+  ) {
+    super(repository);
+  }
+}

From 1e27b96708ee2ac16eee38a1f3edc07f5c9a344b Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 27 Jun 2026 07:18:50 +0000
Subject: [PATCH 03/63] chore: setup migration for invoice

---
 .../1821000000002-CreateInvoices.ts           | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
new file mode 100644
index 000000000..5c42cad65
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -0,0 +1,101 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Freight billing — `invoices` + `invoice_lines` tables.
+ *
+ * Matches:
+ *   - billing/entities/invoice.entity.ts
+ *   - billing/entities/invoice-line.entity.ts
+ *
+ * The status enum mirrors `Freight.InvoiceStatus` and uses TypeORM's default
+ * enum-type name (`<table>_<column>_enum`) so the entity's `type: "enum"`
+ * column resolves to it without an explicit `enumName`.
+ */
+export class CreateInvoices1821000000002 implements MigrationInterface {
+  name = "CreateInvoices1821000000002";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TYPE freight.invoices_status_enum AS ENUM (
+        'DRAFT',
+        'PENDING',
+        'PAID',
+        'OVERDUE',
+        'CANCELLED',
+        'REFUNDED'
+      );
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE freight.invoices (
+        id uuid NOT NULL DEFAULT uuid_generate_v4(),
+        invoice_number varchar(64) NOT NULL,
+        company_id uuid NOT NULL,
+        company_profile_id uuid NOT NULL,
+        total_amount numeric(14, 2) NOT NULL,
+        currency varchar(8) NOT NULL DEFAULT 'ETB',
+        status freight.invoices_status_enum NOT NULL DEFAULT 'DRAFT',
+        source varchar(255) NOT NULL,
+        source_id varchar(255) NOT NULL,
+        type varchar(255) NOT NULL,
+        issued_at timestamptz,
+        payment_id uuid,
+        due_at timestamptz NOT NULL,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz,
+        CONSTRAINT pk_invoices PRIMARY KEY (id),
+        CONSTRAINT uq_invoices_invoice_number UNIQUE (invoice_number),
+        CONSTRAINT fk_invoices_company FOREIGN KEY (company_id)
+          REFERENCES freight.companies (id) ON DELETE RESTRICT,
+        CONSTRAINT fk_invoices_company_profile FOREIGN KEY (company_profile_id)
+          REFERENCES freight.company_profiles (id) ON DELETE RESTRICT,
+        CONSTRAINT fk_invoices_payment FOREIGN KEY (payment_id)
+          REFERENCES freight.payments (id) ON DELETE SET NULL
+      );
+    `);
+
+    await queryRunner.query(
+      `CREATE INDEX idx_invoices_company ON freight.invoices (company_id);`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX idx_invoices_company_profile ON freight.invoices (company_profile_id);`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX idx_invoices_source ON freight.invoices (source, source_id);`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX idx_invoices_status ON freight.invoices (status);`,
+    );
+
+    await queryRunner.query(`
+      CREATE TABLE freight.invoice_lines (
+        id uuid NOT NULL DEFAULT uuid_generate_v4(),
+        invoice_id uuid NOT NULL,
+        charge_type varchar NOT NULL,
+        description varchar(255),
+        quantity numeric(12, 2) NOT NULL DEFAULT 1,
+        unit_rate numeric(14, 2) NOT NULL DEFAULT 0,
+        amount numeric(14, 2) NOT NULL,
+        currency varchar(8) NOT NULL DEFAULT 'ETB',
+        metadata jsonb,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz,
+        CONSTRAINT pk_invoice_lines PRIMARY KEY (id),
+        CONSTRAINT fk_invoice_lines_invoice FOREIGN KEY (invoice_id)
+          REFERENCES freight.invoices (id) ON DELETE CASCADE
+      );
+    `);
+
+    await queryRunner.query(
+      `CREATE INDEX idx_invoice_lines_invoice ON freight.invoice_lines (invoice_id);`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.invoice_lines;`);
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.invoices;`);
+    await queryRunner.query(`DROP TYPE IF EXISTS freight.invoices_status_enum;`);
+  }
+}

From 55c42058d0fdcd9609a9cccbddcc4850a270b91b Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 27 Jun 2026 08:42:18 +0000
Subject: [PATCH 04/63] chore: updating billing logic

---
 .../src/modules/billing/billing.controller.ts |  14 +-
 .../modules/billing/billing.service.spec.ts   | 147 ++++++++
 .../src/modules/billing/billing.service.ts    | 323 +++++++++++++++++-
 3 files changed, 475 insertions(+), 9 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/billing.service.spec.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index 5a801cf73..e3778e11b 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -1,4 +1,4 @@
-import { Controller, Get, Param, ParseUUIDPipe } from "@nestjs/common";
+import { Controller, Get, Param, ParseUUIDPipe, Post } from "@nestjs/common";
 import { ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import { FreightAdmin } from "../../common/booking-guards";
@@ -21,4 +21,16 @@ export class BillingController {
   findByBooking(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
     return this.billingService.findByBooking(bookingId);
   }
+
+  @Get("invoices/:id")
+  @ApiOperation({ summary: "Get an invoice with its line items" })
+  findById(@Param("id", ParseUUIDPipe) id: string) {
+    return this.billingService.findById(id);
+  }
+
+  @Post("invoices/generate/:bookingId")
+  @ApiOperation({ summary: "Generate (or return the existing) invoice for a booking" })
+  generate(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
+    return this.billingService.generateForBooking(bookingId);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
new file mode 100644
index 000000000..4e2d27bb8
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -0,0 +1,147 @@
+import { Freight } from "@edr/types";
+
+import { BillingService } from "./billing.service";
+import type { Invoice } from "./entities/invoice.entity";
+
+/**
+ * Minimal in-memory EntityManager stand-in covering the methods
+ * `generateForBooking` / `markBookingInvoicePaid` call on the transaction manager.
+ */
+function makeManager(savedLines: unknown[]) {
+  return {
+    create: (_entity: unknown, data: Record<string, unknown>) => data,
+    save: (data: Record<string, unknown>) => {
+      const row = { id: data.id ?? `gen-${Math.round(0)}`, ...data };
+      if (data.invoiceId) savedLines.push(row);
+      return Promise.resolve(row);
+    },
+    query: () => Promise.resolve([{ seq: 0 }]),
+    update: jest.fn().mockResolvedValue(undefined),
+    findOne: jest.fn().mockResolvedValue(null),
+  };
+}
+
+function makeBooking(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "booking-1",
+    reference: "BK-001",
+    companyId: "company-1",
+    companyProfileId: "profile-1",
+    paymentCurrency: "ETB",
+    totalAmount: 1500,
+    pricingBreakdown: {
+      currency: "ETB",
+      totalAmount: 1500,
+      lineItems: [
+        { code: "RAIL_FREIGHT", description: "Rail freight", amount: 1000, unitAmount: 500, unit: "PER_CONTAINER", quantity: 2, currency: "ETB" },
+        { code: "HAZARD_SURCHARGE", description: "Hazard surcharge", amount: 500, unitAmount: 250, unit: "PER_CONTAINER", quantity: 2, currency: "ETB" },
+      ],
+    },
+    ...overrides,
+  };
+}
+
+describe("BillingService.generateForBooking", () => {
+  let invoices: { findAll: jest.Mock; findById: jest.Mock };
+  let invoiceLines: { findAll: jest.Mock };
+  let savedLines: unknown[];
+  let manager: ReturnType<typeof makeManager>;
+  let bookingRow: Record<string, unknown> | null;
+  let dataSource: {
+    getRepository: jest.Mock;
+    transaction: jest.Mock;
+    manager: unknown;
+  };
+  let service: BillingService;
+
+  beforeEach(() => {
+    savedLines = [];
+    manager = makeManager(savedLines);
+    invoices = { findAll: jest.fn().mockResolvedValue([]), findById: jest.fn() };
+    invoiceLines = { findAll: jest.fn().mockResolvedValue([]) };
+    bookingRow = makeBooking();
+    dataSource = {
+      getRepository: jest.fn().mockReturnValue({
+        findOne: jest.fn().mockImplementation(() => Promise.resolve(bookingRow)),
+      }),
+      transaction: jest.fn().mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
+      manager,
+    };
+    service = new BillingService(dataSource as never, invoices as never, invoiceLines as never);
+  });
+
+  it("creates a PENDING invoice with one line per pricing line item", async () => {
+    const invoice = (await service.generateForBooking("booking-1")) as Invoice;
+
+    expect(invoice).toBeTruthy();
+    expect(invoice.status).toBe(Freight.InvoiceStatus.Pending);
+    expect(invoice.companyId).toBe("company-1");
+    expect(invoice.companyProfileId).toBe("profile-1");
+    expect(invoice.source).toBe("booking");
+    expect(invoice.sourceId).toBe("booking-1");
+    expect(invoice.totalAmount).toBe(1500);
+    expect(invoice.invoiceNumber).toMatch(/^FRT-\d{8}-00001$/);
+    expect(savedLines).toHaveLength(2);
+  });
+
+  it("returns the existing active invoice instead of creating a duplicate", async () => {
+    const existing = { id: "inv-existing", status: Freight.InvoiceStatus.Pending } as Invoice;
+    invoices.findAll.mockResolvedValueOnce([existing]);
+
+    const invoice = await service.generateForBooking("booking-1");
+
+    expect(invoice).toBe(existing);
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+  });
+
+  it("skips generation (returns null) when the booking has no company to bill", async () => {
+    bookingRow = makeBooking({ companyId: null, companyProfileId: null });
+
+    const invoice = await service.generateForBooking("booking-1");
+
+    expect(invoice).toBeNull();
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+  });
+
+  it("falls back to a single freight line when no pricing breakdown exists", async () => {
+    bookingRow = makeBooking({ pricingBreakdown: null });
+
+    const invoice = (await service.generateForBooking("booking-1")) as Invoice;
+
+    expect(invoice.totalAmount).toBe(1500);
+    expect(savedLines).toHaveLength(1);
+    expect((savedLines[0] as { chargeType: string }).chargeType).toBe("FREIGHT");
+  });
+});
+
+describe("BillingService.markBookingInvoicePaid", () => {
+  it("marks the open booking invoice PAID and links the payment", async () => {
+    const open = { id: "inv-1", status: Freight.InvoiceStatus.Pending };
+    const mg = {
+      findOne: jest.fn().mockResolvedValue(open),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const dataSource = { manager: mg } as never;
+    const service = new BillingService(dataSource, {} as never, {} as never);
+
+    await service.markBookingInvoicePaid("booking-1", "pay-1", mg as never);
+
+    expect(mg.update).toHaveBeenCalledWith(
+      expect.anything(),
+      { id: "inv-1" },
+      { status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" },
+    );
+  });
+
+  it("is a no-op when the booking has no open invoice", async () => {
+    const mg = {
+      findOne: jest.fn().mockResolvedValue(null),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const service = new BillingService({ manager: mg } as never, {} as never, {} as never);
+
+    await service.markBookingInvoicePaid("booking-1", "pay-1", mg as never);
+
+    expect(mg.update).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 39eae6ef5..fd95a12f6 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,26 +1,333 @@
-import { Injectable } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
+import { Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { Freight } from "@edr/types";
+import { DataSource, EntityManager, In } from "typeorm";
 
+import { Booking } from "../bookings/entities/booking.entity";
 import { Invoice } from "./entities/invoice.entity";
+import { InvoiceLine } from "./entities/invoice-line.entity";
+import { InvoiceRepository } from "./invoice.repository";
+import { InvoiceLineRepository } from "./invoice-line.repository";
+
+/** Source tag stamped on booking invoices (`source` column). */
+const BOOKING_SOURCE = "booking";
+
+/** Default invoice payment-term window, in days, used to compute `dueAt`. */
+const DEFAULT_DUE_DAYS = 14;
+
+/**
+ * Statuses an invoice can hold while it still represents the live bill for a
+ * booking. A second `generateForBooking` call returns the existing one of these
+ * instead of creating a duplicate (idempotency / dedup guard).
+ */
+const ACTIVE_STATUSES: Freight.InvoiceStatus[] = [
+  Freight.InvoiceStatus.Draft,
+  Freight.InvoiceStatus.Pending,
+  Freight.InvoiceStatus.Paid,
+  Freight.InvoiceStatus.Overdue,
+];
+
+/** Shape of a single line inside `booking.pricingBreakdown.lineItems`. */
+interface StoredPriceLine {
+  code: string;
+  description: string;
+  amount: number;
+  unitAmount: number;
+  unit: string;
+  quantity: number;
+  currency: string;
+}
+
+interface StoredPricingBreakdown {
+  lineItems?: StoredPriceLine[];
+  totalAmount?: number;
+  currency?: string;
+}
+
+/** A fully-resolved invoice line ready to persist. */
+interface BuiltLine {
+  chargeType: string;
+  description: string;
+  quantity: number;
+  unitRate: number;
+  amount: number;
+  currency: string;
+  metadata?: Record<string, unknown>;
+}
 
 @Injectable()
 export class BillingService {
+  private readonly logger = new Logger(BillingService.name);
+
   constructor(
-    @InjectRepository(Invoice)
-    private readonly invoicesRepository: Repository<Invoice>,
+    private readonly dataSource: DataSource,
+    private readonly invoices: InvoiceRepository,
+    private readonly invoiceLines: InvoiceLineRepository,
   ) {}
 
+  // ── Reads ──────────────────────────────────────────────────────────────────
+
   /** List every invoice (most recent first). */
   findAll(): Promise<Invoice[]> {
-    return this.invoicesRepository.find({ order: { issuedAt: "DESC" } });
+    return this.invoices.findAll({ order: { issuedAt: "DESC" } });
   }
 
   /** List invoices for a given booking. */
   findByBooking(bookingId: string): Promise<Invoice[]> {
-    return this.invoicesRepository.find({
-      where: { bookingId },
+    return this.invoices.findAll({
+      where: { source: BOOKING_SOURCE, sourceId: bookingId },
       order: { issuedAt: "DESC" },
     });
   }
+
+  /** Invoice header plus its line items. */
+  async findById(id: string): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const invoice = await this.invoices.findById(id);
+    if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
+    const lines = await this.invoiceLines.findAll({
+      where: { invoiceId: id },
+      order: { createdAt: "ASC" },
+    });
+    return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
+  }
+
+  // ── Generation ───────────────────────────────────────────────────────────────
+
+  /**
+   * Generate the booking's invoice from its snapshotted pricing breakdown.
+   *
+   * Called when a booking reaches a billable state (full contract execution /
+   * contract activation). Idempotent: a booking that already has an active
+   * invoice gets that invoice back instead of a duplicate.
+   *
+   * Returns `null` (and logs) when the booking is not billable yet — no pricing
+   * breakdown, or no customer company/profile to bill (e.g. government/legacy
+   * bookings whose `company_id` is null, which the `invoices` FK requires).
+   */
+  async generateForBooking(bookingId: string): Promise<Invoice | null> {
+    const existing = await this.invoices.findAll({
+      where: { source: BOOKING_SOURCE, sourceId: bookingId },
+    });
+    const active = existing.find((inv) => ACTIVE_STATUSES.includes(inv.status));
+    if (active) return active;
+
+    const booking = await this.dataSource
+      .getRepository(Booking)
+      .findOne({ where: { id: bookingId } });
+    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
+
+    if (!booking.companyId) {
+      this.logger.warn(
+        `Skipping invoice for booking ${booking.reference} (${bookingId}): no company to bill.`,
+      );
+      return null;
+    }
+    const companyId = booking.companyId;
+    const companyProfileId = booking.companyProfileId ?? null;
+
+    const breakdown = (booking.pricingBreakdown ?? {}) as StoredPricingBreakdown;
+    const currency = breakdown.currency ?? booking.paymentCurrency ?? "ETB";
+    const lines = this.buildLines(breakdown, booking.totalAmount, currency);
+    const subtotal = round2(lines.reduce((sum, l) => sum + l.amount, 0));
+
+    // Honor a staff price override: bill the adjusted total, recording the delta
+    // as an ADJUSTMENT line so the signed lines still sum to the invoice total.
+    const adjusted = booking.adjustedTotalAmount;
+    let total = subtotal;
+    if (adjusted != null && Number.isFinite(Number(adjusted))) {
+      const delta = round2(Number(adjusted) - subtotal);
+      if (delta !== 0) {
+        lines.push({
+          chargeType: "ADJUSTMENT",
+          description: "Staff price adjustment",
+          quantity: 1,
+          unitRate: delta,
+          amount: delta,
+          currency,
+        });
+      }
+      total = round2(Number(adjusted));
+    }
+
+    const issuedAt = new Date();
+    const dueAt = new Date(issuedAt);
+    dueAt.setDate(dueAt.getDate() + DEFAULT_DUE_DAYS);
+
+    return this.dataSource.transaction(async (mg) => {
+      const invoice = await mg.save(
+        mg.create(Invoice, {
+          invoiceNumber: await this.nextInvoiceNumber(mg),
+          companyId,
+          companyProfileId,
+          totalAmount: total,
+          currency,
+          status: Freight.InvoiceStatus.Pending,
+          source: BOOKING_SOURCE,
+          sourceId: bookingId,
+          type: "PREPAID",
+          issuedAt,
+          dueAt,
+        }),
+      );
+
+      for (const line of lines) {
+        await mg.save(mg.create(InvoiceLine, { invoiceId: invoice.id, ...line }));
+      }
+
+      this.logger.log(
+        `Generated invoice ${invoice.invoiceNumber} for booking ${booking.reference} (${total} ${currency}).`,
+      );
+      return invoice;
+    });
+  }
+
+  /** Map the stored pricing line items to invoice lines (one breakdown line → one invoice line). */
+  private buildLines(
+    breakdown: StoredPricingBreakdown,
+    fallbackTotal: number,
+    currency: string,
+  ): BuiltLine[] {
+    const items = breakdown.lineItems ?? [];
+    if (items.length === 0) {
+      // No itemized breakdown — bill a single line for the booking total.
+      return [
+        {
+          chargeType: "FREIGHT",
+          description: "Freight charge",
+          quantity: 1,
+          unitRate: round2(fallbackTotal),
+          amount: round2(fallbackTotal),
+          currency,
+        },
+      ];
+    }
+
+    return items.map((item) => ({
+      chargeType: item.code,
+      description: item.description,
+      quantity: item.quantity,
+      unitRate: round2(item.unitAmount),
+      amount: round2(item.amount),
+      currency: item.currency ?? currency,
+      metadata: { unit: item.unit },
+    }));
+  }
+
+  /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */
+  private async nextInvoiceNumber(mg: EntityManager): Promise<string> {
+    const now = new Date();
+    const ymd = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, "0")}${String(now.getDate()).padStart(2, "0")}`;
+    const prefix = `FRT-${ymd}-`;
+    const [row] = await mg.query(
+      `SELECT COALESCE(MAX(CAST(split_part(invoice_number, '-', 3) AS int)), 0) AS seq
+         FROM freight.invoices WHERE invoice_number LIKE $1`,
+      [`${prefix}%`],
+    );
+    const next = Number(row?.seq ?? 0) + 1;
+    return `${prefix}${String(next).padStart(5, "0")}`;
+  }
+
+  // ── Payment reconciliation ───────────────────────────────────────────────────
+
+  /**
+   * The invoice a gateway payment should settle for a booking, or null if none.
+   *
+   * This is the billing document of record for "what is owed" — callers (e.g.
+   * `payment.service.initiatePayment`) should charge `invoice.totalAmount` against
+   * it rather than recomputing from `booking.totalAmount`, so discounts/penalties/
+   * adjustments carried on the invoice are honored. Returns the most recent open
+   * (unpaid, non-cancelled) invoice.
+   */
+  findPayableForBooking(bookingId: string): Promise<Invoice | null> {
+    return this.dataSource.getRepository(Invoice).findOne({
+      where: {
+        source: BOOKING_SOURCE,
+        sourceId: bookingId,
+        status: In([
+          Freight.InvoiceStatus.Pending,
+          Freight.InvoiceStatus.Draft,
+          Freight.InvoiceStatus.Overdue,
+        ]),
+      },
+      order: { issuedAt: "DESC" },
+    });
+  }
+
+  /**
+   * Mark a booking's paid invoice as refunded. Called from `payment.service.refund`
+   * inside its DB transaction so the invoice tracks the booking/payment reversal.
+   * No-op when the booking has no paid invoice.
+   */
+  async markBookingInvoiceRefunded(
+    bookingId: string,
+    manager?: EntityManager,
+  ): Promise<void> {
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, {
+      where: {
+        source: BOOKING_SOURCE,
+        sourceId: bookingId,
+        status: Freight.InvoiceStatus.Paid,
+      },
+      order: { issuedAt: "DESC" },
+    });
+    if (!invoice) return;
+
+    await mg.update(
+      Invoice,
+      { id: invoice.id },
+      { status: Freight.InvoiceStatus.Refunded },
+    );
+  }
+
+  /**
+   * Mark a booking's open invoice as paid and link the gateway payment.
+   *
+   * Called from `payment.service.finalizePaymentSuccess()` inside its existing DB
+   * transaction (pass the transaction's `EntityManager`). Full-payment only — no
+   * partial settlement in this phase. No-op when the booking has no open invoice.
+   */
+  async markBookingInvoicePaid(
+    bookingId: string,
+    paymentId: string | null,
+    manager?: EntityManager,
+  ): Promise<void> {
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, {
+      where: {
+        source: BOOKING_SOURCE,
+        sourceId: bookingId,
+        status: In([Freight.InvoiceStatus.Pending, Freight.InvoiceStatus.Draft, Freight.InvoiceStatus.Overdue]),
+      },
+      order: { issuedAt: "DESC" },
+    });
+    if (!invoice) return;
+
+    await mg.update(
+      Invoice,
+      { id: invoice.id },
+      { status: Freight.InvoiceStatus.Paid, paymentId: paymentId ?? undefined },
+    );
+  }
+
+  /**
+   * Single settlement chokepoint for any path that marks a booking PAID: ensure
+   * the booking has an invoice (idempotent generate), then mark it paid. Reused by
+   * the gateway flow and offline/manual "mark paid" so invoicing holds everywhere.
+   *
+   * No-op for bookings that have no invoice and cannot get one (e.g. government
+   * bookings with no company to bill — `generateForBooking` returns null).
+   */
+  async settleBookingInvoice(
+    bookingId: string,
+    paymentId: string | null = null,
+    manager?: EntityManager,
+  ): Promise<void> {
+    await this.generateForBooking(bookingId);
+    await this.markBookingInvoicePaid(bookingId, paymentId, manager);
+  }
+}
+
+/** Round to 2 decimal places without float drift. */
+function round2(n: number): number {
+  return Math.round(Number(n) * 100) / 100;
 }

From 98e34593c4eaddf3373c918cd2ffc4788fbac0d3 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 27 Jun 2026 09:08:15 +0000
Subject: [PATCH 05/63] feat: add government support to the companies. add
 seeding and constrain on booking

---
 apps/edr-freight-api/package.json             |   1 +
 apps/edr-freight-api/src/app.module.ts        |   6 +
 ...000003-AddCompanyKindAndGovBookingLinks.ts | 129 +++++++++++++++++
 .../booking-orders/booking-orders.service.ts  |   5 +-
 .../src/modules/bookings/bookings.service.ts  |  46 +++++-
 .../bookings/dto/create-booking.dto.ts        |  23 ++-
 .../bookings/entities/booking.entity.ts       |  15 +-
 .../modules/companies/companies.repository.ts |   6 +-
 .../modules/companies/companies.service.ts    |  23 +++
 .../companies/dto/list-companies-query.dto.ts |   7 +-
 .../companies/entities/company.entity.ts      |  21 +++
 .../src/scripts/seed-gov-companies.ts         |  28 ++++
 .../src/seed/data/gov-companies.data.ts       | 136 ++++++++++++++++++
 .../src/seed/gov-companies.seeder.ts          |  72 ++++++++++
 14 files changed, 495 insertions(+), 23 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts
 create mode 100644 apps/edr-freight-api/src/scripts/seed-gov-companies.ts
 create mode 100644 apps/edr-freight-api/src/seed/data/gov-companies.data.ts
 create mode 100644 apps/edr-freight-api/src/seed/gov-companies.seeder.ts

diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index b26764d30..822e6f5e1 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -20,6 +20,7 @@
     "seed:warehouse-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-warehouse-demo.ts",
     "seed:export-djibouti-interchange-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-export-djibouti-interchange-demo.ts",
     "seed:file-upload-settings": "ts-node -r tsconfig-paths/register src/scripts/seed-file-upload-settings.ts",
+    "seed:gov-companies": "ts-node -r tsconfig-paths/register src/scripts/seed-gov-companies.ts",
     "seed:fleet-wagons": "bash ../../../docs/new/seeds/seed-fleet-wagons.sh"
   },
   "dependencies": {
diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 3b69d2812..a598da8e4 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -54,6 +54,7 @@ import { Batch8TestDataSeeder } from "./seed/batch8-test-data.seeder";
 import { WarehouseDemoSeeder } from "./seed/warehouse-demo.seeder";
 import { FreightPermissionKeyMigrationSeeder } from "./seed/freight-permission-key-migration.seeder";
 import { DemoFreightDataSeeder } from "./seed/demo-freight-data.seeder";
+import { GovCompaniesSeeder } from "./seed/gov-companies.seeder";
 //New Trains, Wagons, Container and Cargo management modules
 import { TrainsModule } from "./modules/trains/trains.module";
 import { WagonsModule } from './modules/wagons/wagons.module';
@@ -139,6 +140,7 @@ import { InterchangeDocumentsModule } from './modules/interchange-documents/inte
     FileUploadSettingsSeeder,
     FreightPermissionKeyMigrationSeeder,
     DemoFreightDataSeeder,
+    GovCompaniesSeeder,
     IndodeFacilitySeeder,
     Batch14TestDataSeeder,
     Batch5TestDataSeeder,
@@ -163,6 +165,7 @@ export class AppModule implements OnApplicationBootstrap {
     private readonly warehouseDemoSeeder: WarehouseDemoSeeder,
     private readonly freightPermissionKeyMigrationSeeder: FreightPermissionKeyMigrationSeeder,
     private readonly demoFreightDataSeeder: DemoFreightDataSeeder,
+    private readonly govCompaniesSeeder: GovCompaniesSeeder,
   ) { }
 
   async onApplicationBootstrap() {
@@ -187,5 +190,8 @@ export class AppModule implements OnApplicationBootstrap {
     // demoFreightDataSeeder now seeds ONLY the 4 staff users (wagons + approval
     // rules are disabled inside the seeder). Kept running for the staff users.
     await this.demoFreightDataSeeder.run();
+    // Government entities (with importer/exporter profiles) that government
+    // bookings bill to. Idempotent — keyed by fixed IDs.
+    await this.govCompaniesSeeder.run();
   }
 }
diff --git a/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts b/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts
new file mode 100644
index 000000000..95ea3db1b
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts
@@ -0,0 +1,129 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Government bookings now bill to a real seeded government company + an explicit
+ * importer/exporter profile, instead of carrying a null company + free-text
+ * institution. This migration:
+ *
+ *   1. Adds `companies.kind` (commercial | government).
+ *   2. Seeds the Ethiopian government entities + their importer/exporter
+ *      profiles (mirrors src/seed/data/gov-companies.data.ts — keep in sync).
+ *   3. Backfills every booking with a NULL company_id / company_profile_id so
+ *      the NOT NULL constraints below can be applied:
+ *        - NULL company_id  → the default government company.
+ *        - NULL company_profile_id → the company's profile matching the booking
+ *          trade direction; else any profile of the company; else the default
+ *          government importer profile.
+ *   4. Enforces NOT NULL on bookings.company_id and bookings.company_profile_id.
+ */
+export class AddCompanyKindAndGovBookingLinks1821000000003
+  implements MigrationInterface
+{
+  name = "AddCompanyKindAndGovBookingLinks1821000000003";
+
+  // Mirrors src/seed/data/gov-companies.data.ts
+  private readonly govCompanies = [
+    { id: "0a1b0001-0000-4000-8000-000000000001", name: "Federal Government of Ethiopia", tin: "0000000001", email: "procurement@gov.et", phone: "+251111000001", im: "0b1c0001-0000-4000-8000-000000000001", ex: "0b1c0001-0000-4000-8000-000000000002", imRef: "IM-90001", exRef: "EX-90001" },
+    { id: "0a1b0002-0000-4000-8000-000000000002", name: "Ministry of National Defense", tin: "0000000002", email: "logistics@mod.gov.et", phone: "+251111000002", im: "0b1c0002-0000-4000-8000-000000000001", ex: "0b1c0002-0000-4000-8000-000000000002", imRef: "IM-90002", exRef: "EX-90002" },
+    { id: "0a1b0003-0000-4000-8000-000000000003", name: "Ethiopian Roads Administration", tin: "0000000003", email: "supply@era.gov.et", phone: "+251111000003", im: "0b1c0003-0000-4000-8000-000000000001", ex: "0b1c0003-0000-4000-8000-000000000002", imRef: "IM-90003", exRef: "EX-90003" },
+    { id: "0a1b0004-0000-4000-8000-000000000004", name: "Ministry of Agriculture", tin: "0000000004", email: "imports@moa.gov.et", phone: "+251111000004", im: "0b1c0004-0000-4000-8000-000000000001", ex: "0b1c0004-0000-4000-8000-000000000002", imRef: "IM-90004", exRef: "EX-90004" },
+    { id: "0a1b0005-0000-4000-8000-000000000005", name: "Ministry of Trade and Regional Integration", tin: "0000000005", email: "trade@motri.gov.et", phone: "+251111000005", im: "0b1c0005-0000-4000-8000-000000000001", ex: "0b1c0005-0000-4000-8000-000000000002", imRef: "IM-90005", exRef: "EX-90005" },
+    { id: "0a1b0006-0000-4000-8000-000000000006", name: "Ethiopian Disaster Risk Management Commission", tin: "0000000006", email: "relief@edrmc.gov.et", phone: "+251111000006", im: "0b1c0006-0000-4000-8000-000000000001", ex: "0b1c0006-0000-4000-8000-000000000002", imRef: "IM-90006", exRef: "EX-90006" },
+  ];
+
+  private get defaultCompanyId(): string {
+    return this.govCompanies[0].id;
+  }
+  private get defaultImporterProfileId(): string {
+    return this.govCompanies[0].im;
+  }
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // 1. kind column
+    await queryRunner.query(
+      `ALTER TABLE "freight"."companies" ADD COLUMN IF NOT EXISTS "kind" varchar(20) NOT NULL DEFAULT 'commercial'`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "IDX_companies_kind" ON "freight"."companies" ("kind")`,
+    );
+
+    // 2. seed government companies + importer/exporter profiles (idempotent)
+    for (const g of this.govCompanies) {
+      await queryRunner.query(
+        `INSERT INTO "freight"."companies" ("id", "name", "type", "kind", "status", "tin", "country", "email", "phone")
+         VALUES ($1, $2, 'customer', 'government', 'active', $3, 'Ethiopia', $4, $5)
+         ON CONFLICT ("id") DO NOTHING`,
+        [g.id, g.name, g.tin, g.email, g.phone],
+      );
+      await queryRunner.query(
+        `INSERT INTO "freight"."company_profiles" ("id", "company_id", "type", "reference", "status")
+         VALUES ($1, $2, 'importer', $3, 'active'), ($4, $2, 'exporter', $5, 'active')
+         ON CONFLICT ("id") DO NOTHING`,
+        [g.im, g.id, g.imRef, g.ex, g.exRef],
+      );
+    }
+
+    // 3a. backfill NULL company_id → default government company
+    await queryRunner.query(
+      `UPDATE "freight"."bookings" SET "company_id" = $1 WHERE "company_id" IS NULL`,
+      [this.defaultCompanyId],
+    );
+
+    // 3b. backfill NULL company_profile_id → profile matching trade direction
+    await queryRunner.query(
+      `UPDATE "freight"."bookings" b
+         SET "company_profile_id" = cp."id"
+         FROM "freight"."company_profiles" cp
+        WHERE b."company_profile_id" IS NULL
+          AND cp."company_id" = b."company_id"
+          AND cp."deleted_at" IS NULL
+          AND cp."type" = CASE b."trade_direction"
+                            WHEN 'IMPORT' THEN 'importer'
+                            WHEN 'EXPORT' THEN 'exporter'
+                            ELSE NULL END`,
+    );
+
+    // 3c. fallback → any profile of the booking's company
+    await queryRunner.query(
+      `UPDATE "freight"."bookings" b
+         SET "company_profile_id" = (
+           SELECT cp."id" FROM "freight"."company_profiles" cp
+            WHERE cp."company_id" = b."company_id" AND cp."deleted_at" IS NULL
+            ORDER BY cp."created_at" ASC LIMIT 1)
+        WHERE b."company_profile_id" IS NULL
+          AND EXISTS (
+            SELECT 1 FROM "freight"."company_profiles" cp
+             WHERE cp."company_id" = b."company_id" AND cp."deleted_at" IS NULL)`,
+    );
+
+    // 3d. final fallback → default government importer profile
+    await queryRunner.query(
+      `UPDATE "freight"."bookings" SET "company_profile_id" = $1 WHERE "company_profile_id" IS NULL`,
+      [this.defaultImporterProfileId],
+    );
+
+    // 4. enforce NOT NULL
+    await queryRunner.query(
+      `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_id" SET NOT NULL`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_profile_id" SET NOT NULL`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_profile_id" DROP NOT NULL`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_id" DROP NOT NULL`,
+    );
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS "freight"."IDX_companies_kind"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "freight"."companies" DROP COLUMN IF EXISTS "kind"`,
+    );
+    // Seeded government rows are intentionally left in place.
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts b/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts
index 3c5bc4019..210b65b3d 100644
--- a/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts
+++ b/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts
@@ -312,8 +312,9 @@ export class BookingOrdersService {
 
     const child = manager.create(Booking, {
       reference,
-      companyId: contract.companyId ?? null,
-      companyProfileId: contract.companyProfileId ?? null,
+      // Drawdown orders inherit the contract's company + profile (both required).
+      companyId: contract.companyId,
+      companyProfileId: contract.companyProfileId,
       isGovernment: contract.isGovernment,
       governmentInstitution: contract.governmentInstitution ?? null,
       contractType: contract.contractType,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index c47064014..578c181bc 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -11,7 +11,7 @@ import { Freight, SchedulingStatus } from '@edr/types';
 // import { CustomersService } from '../customers/customers.service';
 import { CompaniesService } from '../companies/companies.service';
 import { ProfileType } from '../companies/entities/company-profile.entity';
-import { CompanyStatus } from '../companies/entities/company.entity';
+import { CompanyKind, CompanyStatus } from '../companies/entities/company.entity';
 import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
 import { eatDay } from '../train-scheduling/batch-window.util';
 import { FilesService } from '../files/files.service';
@@ -299,10 +299,23 @@ export class BookingsService {
 
     let companyId: string | null | undefined = dto.companyId;
     if (isGovernment) {
-      if (!dto.governmentInstitution?.trim()) {
-        throw new BadRequestException('governmentInstitution is required for government bookings');
+      // Government bookings bill to a real seeded government company + an
+      // explicitly-chosen importer/exporter profile (no more null company +
+      // free-text institution).
+      if (!dto.companyId) {
+        throw new BadRequestException('A government company is required for government bookings');
       }
-      companyId = dto.companyId ?? null;
+      const govCompany = await this.companiesService.findCompanyById(dto.companyId);
+      if (govCompany.kind !== CompanyKind.Government) {
+        throw new BadRequestException('Selected company is not a government entity');
+      }
+      if (govCompany.status !== CompanyStatus.Active) {
+        throw new BadRequestException('Selected government company is not active');
+      }
+      if (!dto.companyProfileId) {
+        throw new BadRequestException('A government company profile is required for government bookings');
+      }
+      companyId = govCompany.id;
     } else if (!companyId) {
       if (!userId) {
         throw new BadRequestException(
@@ -375,7 +388,16 @@ export class BookingsService {
     // so the customer portal can scope lists/KPIs to the active mode. Best-effort
     // for non-government bookings with a resolved company; never blocks creation.
     let companyProfileId: string | null = null;
-    if (!isGovernment && companyId) {
+    if (dto.companyProfileId && companyId) {
+      // Explicit profile pin (government booking, or staff booking on behalf):
+      // must belong to the chosen company and be active.
+      const profile =
+        await this.companiesService.getActiveCompanyProfileForBooking(
+          companyId,
+          dto.companyProfileId,
+        );
+      companyProfileId = profile.id;
+    } else if (companyId) {
       let fallbackType: ProfileType | null = null;
       if (userId) {
         try {
@@ -405,6 +427,16 @@ export class BookingsService {
       }
     }
 
+    // Every booking must link to a company and a company profile.
+    if (!companyId) {
+      throw new BadRequestException('A company is required to create a booking');
+    }
+    if (!companyProfileId) {
+      throw new BadRequestException(
+        'A company profile is required to create a booking — none could be resolved for this company',
+      );
+    }
+
     const needsConsolidation =
       dto.freightType === 'CONTAINER'
         ? await this.needsConsolidation(containers)
@@ -435,10 +467,10 @@ export class BookingsService {
 
     const booking = await this.bookingsRepository.create({
       reference,
-      companyId: companyId ?? null,
+      companyId,
       companyProfileId,
       isGovernment,
-      governmentInstitution: isGovernment ? dto.governmentInstitution!.trim() : null,
+      governmentInstitution: dto.governmentInstitution?.trim() || null,
       trainId: dto.trainId,
       trainScheduleId: dto.trainScheduleId ?? null,
       contractType: dto.contractType,
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts
index 677ef03fd..9380faba5 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts
@@ -14,7 +14,6 @@ import {
   Max,
   MaxLength,
   Min,
-  MinLength,
   Validate,
   ValidateIf,
   ValidateNested,
@@ -104,19 +103,31 @@ export class CreateBookingDto {
   @Transform(({ value }) => value === 'true' || value === true)
   isGovernment?: boolean;
 
-  @ApiPropertyOptional({ description: 'Required when isGovernment is true' })
-  @ValidateIf((o) => o.isGovernment === true)
+  /** @deprecated Government bookings now bill to a real government company. */
+  @ApiPropertyOptional({ description: 'Deprecated: free-text institution (superseded by companyId)' })
+  @IsOptional()
   @IsString()
-  @MinLength(2)
   @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
   governmentInstitution?: string;
 
-  @ApiPropertyOptional({ format: 'uuid', description: 'Admin only: target company' })
-  @ValidateIf((o) => o.isGovernment !== true)
+  @ApiPropertyOptional({
+    format: 'uuid',
+    description:
+      'Target company. Required for staff/government bookings; resolved from the auth token for customer self-bookings.',
+  })
   @IsOptional()
   @IsUUID()
   companyId?: string;
 
+  @ApiPropertyOptional({
+    format: 'uuid',
+    description:
+      'Explicit company profile (importer/exporter). Required for government bookings; commercial bookings auto-resolve from trade direction.',
+  })
+  @IsOptional()
+  @IsUUID()
+  companyProfileId?: string;
+
   @ApiPropertyOptional({ format: 'uuid' })
   @IsOptional()
   @IsUUID()
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
index 00f6e41c1..d95f5997c 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
@@ -105,8 +105,10 @@ export class Booking extends BaseEntity {
   // @JoinColumn({ name: 'customer_id' })
   // customer?: Customer;
 
-  @Column({ name: 'company_id', type: 'uuid', nullable: true })
-  companyId?: string | null;
+  // Every booking is billed to a company — government bookings bill to a seeded
+  // government company (companies.kind = 'government'). Enforced NOT NULL.
+  @Column({ name: 'company_id', type: 'uuid' })
+  companyId!: string;
 
   @ManyToOne(() => Company, { nullable: true })
   @JoinColumn({ name: 'company_id' })
@@ -116,11 +118,12 @@ export class Booking extends BaseEntity {
    * The operational profile (importer/exporter/forwarder) this booking belongs
    * to. Stamped at creation from the booking's trade direction (IMPORT→importer,
    * EXPORT→exporter) or the user's active profile for DOMESTIC/forwarder.
-   * Customer portal lists and dashboard KPIs are scoped by this. Nullable for
-   * legacy/government/staff-created bookings.
+   * Customer portal lists and dashboard KPIs are scoped by this. Required:
+   * commercial bookings resolve it from trade direction / active mode;
+   * government bookings carry the explicitly-picked government profile.
    */
-  @Column({ name: 'company_profile_id', type: 'uuid', nullable: true })
-  companyProfileId?: string | null;
+  @Column({ name: 'company_profile_id', type: 'uuid' })
+  companyProfileId!: string;
 
   @ManyToOne(() => CompanyProfile, { nullable: true })
   @JoinColumn({ name: 'company_profile_id' })
diff --git a/apps/edr-freight-api/src/modules/companies/companies.repository.ts b/apps/edr-freight-api/src/modules/companies/companies.repository.ts
index b31f2939d..15ca85c73 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.repository.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.repository.ts
@@ -38,7 +38,7 @@ export class CompaniesRepository extends BaseRepository<Company> {
   async findPaginated(
     query: ListCompaniesQueryDto,
   ): Promise<{ items: Company[]; total: number }> {
-    const { page = 1, pageSize = 20, search, type, status } = query;
+    const { page = 1, pageSize = 20, search, type, kind, status } = query;
 
     const qb = this.repository
       .createQueryBuilder('company')
@@ -49,6 +49,10 @@ export class CompaniesRepository extends BaseRepository<Company> {
       qb.andWhere('company.type = :type', { type });
     }
 
+    if (kind) {
+      qb.andWhere('company.kind = :kind', { kind });
+    }
+
     if (status) {
       qb.andWhere('company.status = :status', { status });
     }
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index a838495d5..02f77b2e0 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -337,6 +337,29 @@ export class CompaniesService {
     return company;
   }
 
+  /**
+   * Validate an explicitly-chosen company profile for a booking: it must belong
+   * to the booking's company and be Active. Used for government bookings (staff
+   * pick the profile) and any staff booking that pins a profile directly.
+   */
+  async getActiveCompanyProfileForBooking(
+    companyId: string,
+    profileId: string,
+  ): Promise<CompanyProfile> {
+    const profile = await this.companyProfilesRepo.findById(profileId);
+    if (!profile || profile.companyId !== companyId) {
+      throw new BadRequestException(
+        "Selected company profile does not belong to the chosen company",
+      );
+    }
+    if (profile.status !== ProfileStatus.Active) {
+      throw new BadRequestException(
+        "Selected company profile is not active",
+      );
+    }
+    return profile;
+  }
+
   async getCompanyInfoByUserId(
     userId: string,
   ): Promise<{ profile: ExternalProfile; company: Company }> {
diff --git a/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
index c92592286..4dbb932cb 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
@@ -1,7 +1,7 @@
 import { ApiPropertyOptional } from "@nestjs/swagger";
 import { IsIn, IsInt, IsOptional, IsString, Min } from "class-validator";
 import { Transform } from "class-transformer";
-import { CompanyStatus, CompanyType } from "../entities/company.entity";
+import { CompanyKind, CompanyStatus, CompanyType } from "../entities/company.entity";
 
 export class ListCompaniesQueryDto {
   @ApiPropertyOptional({ default: 1 })
@@ -28,6 +28,11 @@ export class ListCompaniesQueryDto {
   @IsIn(Object.values(CompanyType))
   type?: CompanyType;
 
+  @ApiPropertyOptional({ enum: CompanyKind })
+  @IsOptional()
+  @IsIn(Object.values(CompanyKind))
+  kind?: CompanyKind;
+
   @ApiPropertyOptional({ enum: CompanyStatus })
   @IsOptional()
   @IsIn(Object.values(CompanyStatus))
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
index 6702f9f7c..5fe3a3f67 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
@@ -10,6 +10,16 @@ export enum CompanyType {
   Transporter = "transporter",
 }
 
+/**
+ * Sector of the company — orthogonal to {@link CompanyType} (the trade role).
+ * Government bookings are billed to a single seeded `GOVERNMENT` company instead
+ * of carrying a null company + free-text institution.
+ */
+export enum CompanyKind {
+  Commercial = "commercial",
+  Government = "government",
+}
+
 export enum CompanyStatus {
   Active = "active",
   Pending = "pending",
@@ -25,6 +35,7 @@ export enum CompanyNationality {
 @Entity({ schema: "freight", name: "companies" })
 @Index(["tin"])
 @Index(["type"])
+@Index(["kind"])
 export class Company extends BaseEntity {
   @Column({ name: "name", type: "varchar", length: 200 })
   name!: string;
@@ -32,6 +43,16 @@ export class Company extends BaseEntity {
   @Column({ name: "type", type: "varchar", length: 32, enum: CompanyType })
   type!: CompanyType;
 
+  /** Commercial customer vs. the seeded government entity. */
+  @Column({
+    name: "kind",
+    type: "varchar",
+    length: 20,
+    default: CompanyKind.Commercial,
+    enum: CompanyKind,
+  })
+  kind!: CompanyKind;
+
   @Column({
     name: "status",
     type: "varchar",
diff --git a/apps/edr-freight-api/src/scripts/seed-gov-companies.ts b/apps/edr-freight-api/src/scripts/seed-gov-companies.ts
new file mode 100644
index 000000000..41c027905
--- /dev/null
+++ b/apps/edr-freight-api/src/scripts/seed-gov-companies.ts
@@ -0,0 +1,28 @@
+import "reflect-metadata";
+import { config } from "dotenv";
+import { resolve } from "path";
+
+config({ path: resolve(__dirname, "../../.env") });
+
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "../app.module";
+import { GovCompaniesSeeder } from "../seed/gov-companies.seeder";
+
+async function main() {
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ["error", "warn", "log"],
+  });
+
+  try {
+    const seeder = app.get(GovCompaniesSeeder);
+    await seeder.run();
+    console.log("Government companies seeded.");
+  } finally {
+    await app.close();
+  }
+}
+
+main().catch((err) => {
+  console.error("Government companies seed failed:", err);
+  process.exit(1);
+});
diff --git a/apps/edr-freight-api/src/seed/data/gov-companies.data.ts b/apps/edr-freight-api/src/seed/data/gov-companies.data.ts
new file mode 100644
index 000000000..841441147
--- /dev/null
+++ b/apps/edr-freight-api/src/seed/data/gov-companies.data.ts
@@ -0,0 +1,136 @@
+import {
+  CompanyKind,
+  CompanyStatus,
+  CompanyType,
+} from "../../modules/companies/entities/company.entity";
+import {
+  ProfileStatus,
+  ProfileType,
+} from "../../modules/companies/entities/company-profile.entity";
+
+/**
+ * Canonical list of seeded Ethiopian government entities. Government bookings
+ * are billed to one of these (with an explicit importer/exporter profile)
+ * instead of carrying a null company + free-text institution.
+ *
+ * IDs are fixed so the seeder is idempotent and the matching migration
+ * (1821000000003-AddCompanyKindAndGovBookingLinks) can backfill legacy rows to
+ * the same companies. The migration mirrors these rows in raw SQL — keep both
+ * in sync when adding new entities.
+ */
+
+export const GOV_COMPANY_TYPE = CompanyType.Customer;
+export const GOV_COMPANY_KIND = CompanyKind.Government;
+export const GOV_COMPANY_STATUS = CompanyStatus.Active;
+export const GOV_PROFILE_STATUS = ProfileStatus.Active;
+
+export interface GovProfileSeed {
+  id: string;
+  type: ProfileType;
+  reference: string;
+}
+
+export interface GovCompanySeed {
+  id: string;
+  name: string;
+  tin: string;
+  email: string;
+  phone: string;
+  profiles: GovProfileSeed[];
+}
+
+const importExport = (
+  index: number,
+  importerId: string,
+  exporterId: string,
+): GovProfileSeed[] => [
+  {
+    id: importerId,
+    type: ProfileType.importer,
+    reference: `IM-9000${index}`,
+  },
+  {
+    id: exporterId,
+    type: ProfileType.exporter,
+    reference: `EX-9000${index}`,
+  },
+];
+
+export const GOV_COMPANIES: GovCompanySeed[] = [
+  {
+    id: "0a1b0001-0000-4000-8000-000000000001",
+    name: "Federal Government of Ethiopia",
+    tin: "0000000001",
+    email: "procurement@gov.et",
+    phone: "+251111000001",
+    profiles: importExport(
+      1,
+      "0b1c0001-0000-4000-8000-000000000001",
+      "0b1c0001-0000-4000-8000-000000000002",
+    ),
+  },
+  {
+    id: "0a1b0002-0000-4000-8000-000000000002",
+    name: "Ministry of National Defense",
+    tin: "0000000002",
+    email: "logistics@mod.gov.et",
+    phone: "+251111000002",
+    profiles: importExport(
+      2,
+      "0b1c0002-0000-4000-8000-000000000001",
+      "0b1c0002-0000-4000-8000-000000000002",
+    ),
+  },
+  {
+    id: "0a1b0003-0000-4000-8000-000000000003",
+    name: "Ethiopian Roads Administration",
+    tin: "0000000003",
+    email: "supply@era.gov.et",
+    phone: "+251111000003",
+    profiles: importExport(
+      3,
+      "0b1c0003-0000-4000-8000-000000000001",
+      "0b1c0003-0000-4000-8000-000000000002",
+    ),
+  },
+  {
+    id: "0a1b0004-0000-4000-8000-000000000004",
+    name: "Ministry of Agriculture",
+    tin: "0000000004",
+    email: "imports@moa.gov.et",
+    phone: "+251111000004",
+    profiles: importExport(
+      4,
+      "0b1c0004-0000-4000-8000-000000000001",
+      "0b1c0004-0000-4000-8000-000000000002",
+    ),
+  },
+  {
+    id: "0a1b0005-0000-4000-8000-000000000005",
+    name: "Ministry of Trade and Regional Integration",
+    tin: "0000000005",
+    email: "trade@motri.gov.et",
+    phone: "+251111000005",
+    profiles: importExport(
+      5,
+      "0b1c0005-0000-4000-8000-000000000001",
+      "0b1c0005-0000-4000-8000-000000000002",
+    ),
+  },
+  {
+    id: "0a1b0006-0000-4000-8000-000000000006",
+    name: "Ethiopian Disaster Risk Management Commission",
+    tin: "0000000006",
+    email: "relief@edrmc.gov.et",
+    phone: "+251111000006",
+    profiles: importExport(
+      6,
+      "0b1c0006-0000-4000-8000-000000000001",
+      "0b1c0006-0000-4000-8000-000000000002",
+    ),
+  },
+];
+
+/** Fallback entity used to backfill legacy government / null-company bookings. */
+export const DEFAULT_GOV_COMPANY = GOV_COMPANIES[0];
+export const DEFAULT_GOV_IMPORTER_PROFILE = GOV_COMPANIES[0].profiles[0];
diff --git a/apps/edr-freight-api/src/seed/gov-companies.seeder.ts b/apps/edr-freight-api/src/seed/gov-companies.seeder.ts
new file mode 100644
index 000000000..4fdd250e5
--- /dev/null
+++ b/apps/edr-freight-api/src/seed/gov-companies.seeder.ts
@@ -0,0 +1,72 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { DataSource } from "typeorm";
+
+import { Company } from "../modules/companies/entities/company.entity";
+import { CompanyProfile } from "../modules/companies/entities/company-profile.entity";
+import {
+  GOV_COMPANIES,
+  GOV_COMPANY_KIND,
+  GOV_COMPANY_STATUS,
+  GOV_COMPANY_TYPE,
+  GOV_PROFILE_STATUS,
+} from "./data/gov-companies.data";
+
+/**
+ * Idempotently seeds the Ethiopian government entities (with importer + exporter
+ * profiles) that government bookings bill to. Safe to re-run — rows are keyed by
+ * the fixed IDs in {@link GOV_COMPANIES}; existing rows are left untouched.
+ */
+@Injectable()
+export class GovCompaniesSeeder {
+  private readonly logger = new Logger(GovCompaniesSeeder.name);
+
+  constructor(private readonly dataSource: DataSource) {}
+
+  async run(): Promise<void> {
+    await this.dataSource.transaction(async (manager) => {
+      const companyRepo = manager.getRepository(Company);
+      const profileRepo = manager.getRepository(CompanyProfile);
+
+      for (const gov of GOV_COMPANIES) {
+        const existing = await companyRepo.findOne({ where: { id: gov.id } });
+        if (!existing) {
+          await companyRepo.save(
+            companyRepo.create({
+              id: gov.id,
+              name: gov.name,
+              type: GOV_COMPANY_TYPE,
+              kind: GOV_COMPANY_KIND,
+              status: GOV_COMPANY_STATUS,
+              tin: gov.tin,
+              country: "Ethiopia",
+              email: gov.email,
+              phone: gov.phone,
+            }),
+          );
+          this.logger.log(`Created government company: ${gov.name}`);
+        }
+
+        for (const profile of gov.profiles) {
+          const existingProfile = await profileRepo.findOne({
+            where: { id: profile.id },
+          });
+          if (existingProfile) continue;
+          await profileRepo.save(
+            profileRepo.create({
+              id: profile.id,
+              companyId: gov.id,
+              type: profile.type,
+              reference: profile.reference,
+              status: GOV_PROFILE_STATUS,
+            }),
+          );
+          this.logger.log(
+            `Created ${profile.type} profile ${profile.reference} for ${gov.name}`,
+          );
+        }
+      }
+    });
+
+    this.logger.log("Government companies seeded.");
+  }
+}

From db305d6fcdbc62c1908350ee5d38df5d567418c1 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 27 Jun 2026 09:16:39 +0000
Subject: [PATCH 06/63] chore: add company select to backoffice booking

---
 .../src/pages/bookings/NewBookingPage.tsx     | 81 ++++++++++++++++---
 .../backoffice/src/types/customer.ts          |  5 ++
 2 files changed, 74 insertions(+), 12 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
index e685a3cf4..690da9998 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
@@ -180,8 +180,10 @@ export default function NewBookingPage() {
   const queryClient = useQueryClient();
 
   const [isGovernment, setIsGovernment] = useState(false);
-  const [governmentInstitution, setGovernmentInstitution] = useState("");
   const [companyId, setCompanyId] = useState<string | null>(null);
+  // Government bookings bill to a real government company + an explicit profile.
+  const [govCompanyId, setGovCompanyId] = useState<string | null>(null);
+  const [govProfileId, setGovProfileId] = useState<string | null>(null);
   const [freightType, setFreightType] = useState<FreightType>("CONTAINER");
   const [originYardId, setOriginYardId] = useState<string | null>(null);
   const [destinationYardId, setDestinationYardId] = useState<string | null>(null);
@@ -220,6 +222,42 @@ export default function NewBookingPage() {
     label: c.name || c.email || c.tin || c.id,
   }));
 
+  // Active government companies (kind=government) the booking can bill to.
+  const { data: govCompaniesPage, isLoading: govCompaniesLoading } = useQuery({
+    queryKey: ["companies", "government", "active"],
+    queryFn: () =>
+      customersService.list({
+        page: 1,
+        pageSize: 1000,
+        kind: "government",
+        status: "active",
+      }),
+    enabled: isGovernment,
+  });
+
+  const govCompanies = govCompaniesPage?.items ?? [];
+  const govCompanyOptions = govCompanies.map((c) => ({
+    value: c.id,
+    label: c.name || c.tin || c.id,
+  }));
+
+  // Profiles (importer/exporter) of the chosen government company — the booking
+  // must link to one explicitly.
+  const selectedGovCompany = govCompanies.find((c) => c.id === govCompanyId);
+  const govProfileOptions = (selectedGovCompany?.companyProfiles ?? [])
+    .filter((p) => p.status === "active")
+    .map((p) => ({
+      value: p.id,
+      label: `${p.type === "importer" ? "Import" : p.type === "exporter" ? "Export" : p.type}${
+        p.reference ? ` — ${p.reference}` : ""
+      }`,
+    }));
+
+  // Reset the chosen profile when the government company changes.
+  useEffect(() => {
+    setGovProfileId(null);
+  }, [govCompanyId]);
+
   // Day-level pool: fetch only the days that have a departure on the route (no
   // train, no capacity). The batch engine assigns the train after booking.
   const { data: availableDays, isLoading: daysLoading } = useQuery(
@@ -306,7 +344,7 @@ export default function NewBookingPage() {
     Boolean(tradeDirection) &&
     Boolean(serviceTypeId) &&
     departureSatisfied &&
-    (isGovernment ? governmentInstitution.trim().length >= 2 : Boolean(companyId)) &&
+    (isGovernment ? Boolean(govCompanyId && govProfileId) : Boolean(companyId)) &&
     (freightType === "BULK"
       ? Boolean(cargoTypeId) && bulkWeight > 0
       : allLinesValid);
@@ -320,8 +358,8 @@ export default function NewBookingPage() {
     mutationFn: () =>
       bookingsService.create({
         isGovernment,
-        governmentInstitution: isGovernment ? governmentInstitution : undefined,
-        companyId: isGovernment ? undefined : companyId || undefined,
+        companyId: isGovernment ? govCompanyId || undefined : companyId || undefined,
+        companyProfileId: isGovernment ? govProfileId || undefined : undefined,
         freightType,
         contractType: "NEW",
         equipmentReturn,
@@ -390,18 +428,37 @@ export default function NewBookingPage() {
               <Stack gap="md">
                 <Switch
                   label="Government booking"
-                  description="No company required — institution name instead. Expedited to the scheduling queue."
+                  description="Bills to a government entity + profile. Expedited to the scheduling queue."
                   checked={isGovernment}
                   onChange={(e) => setIsGovernment(e.currentTarget.checked)}
                 />
                 {isGovernment ? (
-                  <TextInput
-                    label="Government institution"
-                    placeholder="e.g. Ministry of Transport"
-                    value={governmentInstitution}
-                    onChange={(e) => setGovernmentInstitution(e.currentTarget.value)}
-                    required
-                  />
+                  <Group grow align="flex-start">
+                    <Select
+                      label="Government entity"
+                      placeholder="Select government company"
+                      data={govCompanyOptions}
+                      value={govCompanyId}
+                      onChange={setGovCompanyId}
+                      searchable
+                      required
+                      disabled={govCompaniesLoading}
+                      nothingFoundMessage="No active government companies"
+                    />
+                    <Select
+                      label="Profile"
+                      placeholder={
+                        govCompanyId ? "Select import/export profile" : "Pick an entity first"
+                      }
+                      data={govProfileOptions}
+                      value={govProfileId}
+                      onChange={setGovProfileId}
+                      searchable
+                      required
+                      disabled={!govCompanyId}
+                      nothingFoundMessage="No active profiles for this entity"
+                    />
+                  </Group>
                 ) : (
                   <Select
                     label="Customer"
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index 0cdccc10b..638ab98cd 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -18,6 +18,9 @@ export type CompanyType =
 /** Mirrors backend `CompanyStatus`. */
 export type CompanyStatus = "active" | "pending" | "suspended" | "blacklisted";
 
+/** Mirrors backend `CompanyKind` — commercial customer vs. government entity. */
+export type CompanyKind = "commercial" | "government";
+
 /** Mirrors backend `ProfileType` (the role a company plays). */
 export type ProfileType =
   | "importer"
@@ -47,6 +50,7 @@ export interface Company {
   id: string;
   name: string;
   type: CompanyType;
+  kind: CompanyKind;
   status: CompanyStatus;
   tin: string;
   vatNumber?: string | null;
@@ -73,6 +77,7 @@ export interface CompanyListFilter {
   pageSize: number;
   search?: string;
   type?: CompanyType;
+  kind?: CompanyKind;
   status?: CompanyStatus;
 }
 

From 5bad245ce8f871c1c5b3048f5a8b0610479494f4 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 07:11:52 +0000
Subject: [PATCH 07/63] feat: setup billing services

---
 apps/edr-freight-api/src/app.module.ts        |   3 +-
 .../src/modules/billing/billing.controller.ts |  14 +-
 .../modules/billing/billing.service.spec.ts   | 190 +++---
 .../src/modules/billing/billing.service.ts    | 542 ++++++++++--------
 packages/types/src/freight/index.ts           |   8 +
 5 files changed, 419 insertions(+), 338 deletions(-)

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index a598da8e4..fff3dc8f1 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -2,6 +2,7 @@ import { Module, OnApplicationBootstrap } from "@nestjs/common";
 import { ConfigModule, ConfigService } from "@nestjs/config";
 import { TypeOrmModule, TypeOrmModuleOptions } from "@nestjs/typeorm";
 import { ScheduleModule } from "@nestjs/schedule";
+import { EventEmitterModule } from "@nestjs/event-emitter";
 import { DataSource, DataSourceOptions } from "typeorm";
 import { ensurePostgresSchemas } from "./config/ensure-postgres-schemas";
 import { IamModule, DataSeeder } from "@tria-plc/iamapi-common";
@@ -76,7 +77,7 @@ import { InterchangeDocumentsModule } from './modules/interchange-documents/inte
       load: [appConfig, databaseConfig, telebirrConfig, rabbitmqConfig],
     }),
     ScheduleModule.forRoot(),
-    // EventEmitterModule.forRoot(),
+    EventEmitterModule.forRoot(),
     TypeOrmModule.forRootAsync({
       inject: [ConfigService],
       useFactory: (config: ConfigService): TypeOrmModuleOptions =>
diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index e3778e11b..e7ac41704 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -8,7 +8,7 @@ import { BillingService } from "./billing.service";
 @Controller("billing")
 @FreightAdmin()
 export class BillingController {
-  constructor(private readonly billingService: BillingService) {}
+  constructor(private readonly billingService: BillingService) { }
 
   @Get("invoices")
   @ApiOperation({ summary: "List all invoices" })
@@ -16,21 +16,9 @@ export class BillingController {
     return this.billingService.findAll();
   }
 
-  @Get("invoices/booking/:bookingId")
-  @ApiOperation({ summary: "List invoices for a booking" })
-  findByBooking(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
-    return this.billingService.findByBooking(bookingId);
-  }
-
   @Get("invoices/:id")
   @ApiOperation({ summary: "Get an invoice with its line items" })
   findById(@Param("id", ParseUUIDPipe) id: string) {
     return this.billingService.findById(id);
   }
-
-  @Post("invoices/generate/:bookingId")
-  @ApiOperation({ summary: "Generate (or return the existing) invoice for a booking" })
-  generate(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
-    return this.billingService.generateForBooking(bookingId);
-  }
 }
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 4e2d27bb8..62b3cebaa 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -1,17 +1,16 @@
 import { Freight } from "@edr/types";
 
 import { BillingService } from "./billing.service";
-import type { Invoice } from "./entities/invoice.entity";
 
 /**
  * Minimal in-memory EntityManager stand-in covering the methods
- * `generateForBooking` / `markBookingInvoicePaid` call on the transaction manager.
+ * `generateInvoice` / `markInvoiceAsPaid` call on the transaction manager.
  */
 function makeManager(savedLines: unknown[]) {
   return {
     create: (_entity: unknown, data: Record<string, unknown>) => data,
     save: (data: Record<string, unknown>) => {
-      const row = { id: data.id ?? `gen-${Math.round(0)}`, ...data };
+      const row = { id: data.id ?? "gen-1", ...data };
       if (data.invoiceId) savedLines.push(row);
       return Promise.resolve(row);
     },
@@ -21,127 +20,176 @@ function makeManager(savedLines: unknown[]) {
   };
 }
 
-function makeBooking(overrides: Record<string, unknown> = {}) {
+function makeEvents() {
+  return { emit: jest.fn() };
+}
+
+function generateInput(overrides: Record<string, unknown> = {}) {
   return {
-    id: "booking-1",
-    reference: "BK-001",
+    source: Freight.InvoiceSource.Booking,
+    sourceId: "booking-1",
+    type: "prepaid",
     companyId: "company-1",
     companyProfileId: "profile-1",
-    paymentCurrency: "ETB",
-    totalAmount: 1500,
-    pricingBreakdown: {
-      currency: "ETB",
-      totalAmount: 1500,
-      lineItems: [
-        { code: "RAIL_FREIGHT", description: "Rail freight", amount: 1000, unitAmount: 500, unit: "PER_CONTAINER", quantity: 2, currency: "ETB" },
-        { code: "HAZARD_SURCHARGE", description: "Hazard surcharge", amount: 500, unitAmount: 250, unit: "PER_CONTAINER", quantity: 2, currency: "ETB" },
-      ],
-    },
+    currency: "ETB",
+    lines: [
+      { chargeType: "RAIL_FREIGHT", description: "Rail freight", quantity: 2, unitRate: 500, amount: 1000 },
+      { chargeType: "HAZARD_SURCHARGE", description: "Hazard surcharge", quantity: 2, unitRate: 250, amount: 500 },
+    ],
     ...overrides,
   };
 }
 
-describe("BillingService.generateForBooking", () => {
-  let invoices: { findAll: jest.Mock; findById: jest.Mock };
-  let invoiceLines: { findAll: jest.Mock };
+describe("BillingService.generateInvoice", () => {
   let savedLines: unknown[];
   let manager: ReturnType<typeof makeManager>;
-  let bookingRow: Record<string, unknown> | null;
-  let dataSource: {
-    getRepository: jest.Mock;
-    transaction: jest.Mock;
-    manager: unknown;
-  };
+  let events: ReturnType<typeof makeEvents>;
+  let dataSource: { transaction: jest.Mock; manager: unknown };
   let service: BillingService;
 
   beforeEach(() => {
     savedLines = [];
     manager = makeManager(savedLines);
-    invoices = { findAll: jest.fn().mockResolvedValue([]), findById: jest.fn() };
-    invoiceLines = { findAll: jest.fn().mockResolvedValue([]) };
-    bookingRow = makeBooking();
+    events = makeEvents();
     dataSource = {
-      getRepository: jest.fn().mockReturnValue({
-        findOne: jest.fn().mockImplementation(() => Promise.resolve(bookingRow)),
-      }),
       transaction: jest.fn().mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
       manager,
     };
-    service = new BillingService(dataSource as never, invoices as never, invoiceLines as never);
+    service = new BillingService(dataSource as never, {} as never, {} as never, events as never);
   });
 
-  it("creates a PENDING invoice with one line per pricing line item", async () => {
-    const invoice = (await service.generateForBooking("booking-1")) as Invoice;
+  it("creates a PENDING invoice with one line per input line", async () => {
+    const invoice = await service.generateInvoice(generateInput());
 
-    expect(invoice).toBeTruthy();
     expect(invoice.status).toBe(Freight.InvoiceStatus.Pending);
     expect(invoice.companyId).toBe("company-1");
-    expect(invoice.companyProfileId).toBe("profile-1");
     expect(invoice.source).toBe("booking");
     expect(invoice.sourceId).toBe("booking-1");
     expect(invoice.totalAmount).toBe(1500);
+    expect(invoice.issuedAt).toBeInstanceOf(Date);
     expect(invoice.invoiceNumber).toMatch(/^FRT-\d{8}-00001$/);
     expect(savedLines).toHaveLength(2);
   });
 
-  it("returns the existing active invoice instead of creating a duplicate", async () => {
-    const existing = { id: "inv-existing", status: Freight.InvoiceStatus.Pending } as Invoice;
-    invoices.findAll.mockResolvedValueOnce([existing]);
-
-    const invoice = await service.generateForBooking("booking-1");
-
-    expect(invoice).toBe(existing);
-    expect(dataSource.transaction).not.toHaveBeenCalled();
-  });
-
-  it("skips generation (returns null) when the booking has no company to bill", async () => {
-    bookingRow = makeBooking({ companyId: null, companyProfileId: null });
-
-    const invoice = await service.generateForBooking("booking-1");
-
-    expect(invoice).toBeNull();
-    expect(dataSource.transaction).not.toHaveBeenCalled();
-  });
-
-  it("falls back to a single freight line when no pricing breakdown exists", async () => {
-    bookingRow = makeBooking({ pricingBreakdown: null });
-
-    const invoice = (await service.generateForBooking("booking-1")) as Invoice;
-
+  it("sums line amounts when no explicit totalAmount is given", async () => {
+    const invoice = await service.generateInvoice(
+      generateInput({ totalAmount: undefined }),
+    );
     expect(invoice.totalAmount).toBe(1500);
-    expect(savedLines).toHaveLength(1);
-    expect((savedLines[0] as { chargeType: string }).chargeType).toBe("FREIGHT");
+  });
+
+  it("leaves issuedAt null for a DRAFT invoice", async () => {
+    const invoice = await service.generateInvoice(
+      generateInput({ status: Freight.InvoiceStatus.Draft }),
+    );
+    expect(invoice.status).toBe(Freight.InvoiceStatus.Draft);
+    expect(invoice.issuedAt).toBeNull();
+  });
+
+  it("enlists in a caller's transaction when a manager is passed", async () => {
+    await service.generateInvoice(generateInput(), manager as never);
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+    expect(savedLines).toHaveLength(2);
   });
 });
 
-describe("BillingService.markBookingInvoicePaid", () => {
-  it("marks the open booking invoice PAID and links the payment", async () => {
-    const open = { id: "inv-1", status: Freight.InvoiceStatus.Pending };
+describe("BillingService.markInvoiceAsPaid", () => {
+  it("marks the invoice PAID, links the payment, and emits ${source}.invoice.paid", async () => {
+    const open = {
+      id: "inv-1",
+      status: Freight.InvoiceStatus.Pending,
+      source: "booking",
+      sourceId: "booking-1",
+    };
     const mg = {
       findOne: jest.fn().mockResolvedValue(open),
       update: jest.fn().mockResolvedValue(undefined),
     };
-    const dataSource = { manager: mg } as never;
-    const service = new BillingService(dataSource, {} as never, {} as never);
+    const events = makeEvents();
+    const service = new BillingService(
+      { manager: mg } as never,
+      {} as never,
+      {} as never,
+      events as never,
+    );
 
-    await service.markBookingInvoicePaid("booking-1", "pay-1", mg as never);
+    await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
 
     expect(mg.update).toHaveBeenCalledWith(
       expect.anything(),
       { id: "inv-1" },
       { status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" },
     );
+    expect(events.emit).toHaveBeenCalledWith(
+      "booking.invoice.paid",
+      expect.objectContaining({ invoiceId: "inv-1", status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" }),
+    );
   });
 
-  it("is a no-op when the booking has no open invoice", async () => {
+  it("is a no-op (no event) when the invoice is already paid", async () => {
+    const paid = { id: "inv-1", status: Freight.InvoiceStatus.Paid, source: "booking" };
+    const mg = {
+      findOne: jest.fn().mockResolvedValue(paid),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const events = makeEvents();
+    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
+
+    await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
+
+    expect(mg.update).not.toHaveBeenCalled();
+    expect(events.emit).not.toHaveBeenCalled();
+  });
+});
+
+describe("BillingService.settlePayable", () => {
+  it("settles the source's open invoice PAID and emits ${source}.invoice.paid", async () => {
+    const open = {
+      id: "inv-1",
+      status: Freight.InvoiceStatus.Pending,
+      source: Freight.InvoiceSource.Booking,
+      sourceId: "booking-1",
+    };
+    const mg = {
+      findOne: jest.fn().mockResolvedValue(open),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const events = makeEvents();
+    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
+
+    const settled = await service.settlePayable(
+      Freight.InvoiceSource.Booking,
+      "booking-1",
+      "pay-1",
+      mg as never,
+    );
+
+    expect(settled?.status).toBe(Freight.InvoiceStatus.Paid);
+    expect(mg.update).toHaveBeenCalledWith(
+      expect.anything(),
+      { id: "inv-1" },
+      { status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" },
+    );
+    expect(events.emit).toHaveBeenCalledWith("booking.invoice.paid", expect.anything());
+  });
+
+  it("is a no-op (returns null) when the source has no open invoice", async () => {
     const mg = {
       findOne: jest.fn().mockResolvedValue(null),
       update: jest.fn().mockResolvedValue(undefined),
     };
-    const service = new BillingService({ manager: mg } as never, {} as never, {} as never);
+    const events = makeEvents();
+    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
 
-    await service.markBookingInvoicePaid("booking-1", "pay-1", mg as never);
+    const settled = await service.settlePayable(
+      Freight.InvoiceSource.Booking,
+      "booking-1",
+      "pay-1",
+      mg as never,
+    );
 
+    expect(settled).toBeNull();
     expect(mg.update).not.toHaveBeenCalled();
+    expect(events.emit).not.toHaveBeenCalled();
   });
 });
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index fd95a12f6..ff41eb4e6 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,57 +1,74 @@
 import { Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { EventEmitter2 } from "@nestjs/event-emitter";
 import { Freight } from "@edr/types";
 import { DataSource, EntityManager, In } from "typeorm";
 
-import { Booking } from "../bookings/entities/booking.entity";
 import { Invoice } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
 
-/** Source tag stamped on booking invoices (`source` column). */
-const BOOKING_SOURCE = "booking";
-
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
 const DEFAULT_DUE_DAYS = 14;
 
-/**
- * Statuses an invoice can hold while it still represents the live bill for a
- * booking. A second `generateForBooking` call returns the existing one of these
- * instead of creating a duplicate (idempotency / dedup guard).
- */
-const ACTIVE_STATUSES: Freight.InvoiceStatus[] = [
+/** Statuses an invoice can still be settled (paid/refunded/cancelled) from. */
+const OPEN_STATUSES: Freight.InvoiceStatus[] = [
   Freight.InvoiceStatus.Draft,
   Freight.InvoiceStatus.Pending,
-  Freight.InvoiceStatus.Paid,
   Freight.InvoiceStatus.Overdue,
 ];
 
-/** Shape of a single line inside `booking.pricingBreakdown.lineItems`. */
-interface StoredPriceLine {
-  code: string;
-  description: string;
-  amount: number;
-  unitAmount: number;
-  unit: string;
-  quantity: number;
-  currency: string;
-}
-
-interface StoredPricingBreakdown {
-  lineItems?: StoredPriceLine[];
-  totalAmount?: number;
-  currency?: string;
-}
-
-/** A fully-resolved invoice line ready to persist. */
-interface BuiltLine {
+/** A single line to bill on a generated invoice. */
+export interface InvoiceLineInput {
   chargeType: string;
-  description: string;
-  quantity: number;
-  unitRate: number;
-  amount: number;
+  description?: string;
+  /** Units this line bills for; defaults to 1. */
+  quantity?: number;
+  /** Price per unit; defaults to 0. */
+  unitRate?: number;
+  /** Line total; defaults to `quantity * unitRate`. */
+  amount?: number;
+  currency?: string;
+  metadata?: Record<string, unknown> | null;
+}
+
+/** Everything needed to generate an invoice for any source. */
+export interface GenerateInvoiceInput {
+  /** Originating subsystem; namespaces events (`${source}.invoice.<event>`). */
+  source: Freight.InvoiceSource;
+  /** Identifier of the source record (e.g. booking id). */
+  sourceId: string;
+  /** What the invoice is for (e.g. "prepaid", "credit"). */
+  type: string;
+  companyId: string;
+  companyProfileId: string;
+  lines: InvoiceLineInput[];
+  currency?: string;
+  /** Explicit total; defaults to the sum of line amounts. */
+  totalAmount?: number;
+  /** Issue date window; defaults to `DEFAULT_DUE_DAYS` from now. */
+  dueAt?: Date;
+  dueInDays?: number;
+  /**
+   * Initial status. DRAFT leaves `issuedAt` null; any issued status
+   * (default PENDING) stamps `issuedAt`.
+   */
+  status?: Freight.InvoiceStatus;
+}
+
+/** Payload broadcast on `${source}.invoice.<event>`. */
+export interface InvoiceEventPayload {
+  invoiceId: string;
+  invoiceNumber: string;
+  source: Freight.InvoiceSource;
+  sourceId: string;
+  type: string;
+  companyId: string;
+  companyProfileId: string;
+  totalAmount: number;
   currency: string;
-  metadata?: Record<string, unknown>;
+  status: Freight.InvoiceStatus;
+  paymentId?: string | null;
 }
 
 @Injectable()
@@ -62,7 +79,8 @@ export class BillingService {
     private readonly dataSource: DataSource,
     private readonly invoices: InvoiceRepository,
     private readonly invoiceLines: InvoiceLineRepository,
-  ) {}
+    private readonly events: EventEmitter2,
+  ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
 
@@ -71,14 +89,6 @@ export class BillingService {
     return this.invoices.findAll({ order: { issuedAt: "DESC" } });
   }
 
-  /** List invoices for a given booking. */
-  findByBooking(bookingId: string): Promise<Invoice[]> {
-    return this.invoices.findAll({
-      where: { source: BOOKING_SOURCE, sourceId: bookingId },
-      order: { issuedAt: "DESC" },
-    });
-  }
-
   /** Invoice header plus its line items. */
   async findById(id: string): Promise<Invoice & { lines: InvoiceLine[] }> {
     const invoice = await this.invoices.findById(id);
@@ -92,126 +102,6 @@ export class BillingService {
 
   // ── Generation ───────────────────────────────────────────────────────────────
 
-  /**
-   * Generate the booking's invoice from its snapshotted pricing breakdown.
-   *
-   * Called when a booking reaches a billable state (full contract execution /
-   * contract activation). Idempotent: a booking that already has an active
-   * invoice gets that invoice back instead of a duplicate.
-   *
-   * Returns `null` (and logs) when the booking is not billable yet — no pricing
-   * breakdown, or no customer company/profile to bill (e.g. government/legacy
-   * bookings whose `company_id` is null, which the `invoices` FK requires).
-   */
-  async generateForBooking(bookingId: string): Promise<Invoice | null> {
-    const existing = await this.invoices.findAll({
-      where: { source: BOOKING_SOURCE, sourceId: bookingId },
-    });
-    const active = existing.find((inv) => ACTIVE_STATUSES.includes(inv.status));
-    if (active) return active;
-
-    const booking = await this.dataSource
-      .getRepository(Booking)
-      .findOne({ where: { id: bookingId } });
-    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
-
-    if (!booking.companyId) {
-      this.logger.warn(
-        `Skipping invoice for booking ${booking.reference} (${bookingId}): no company to bill.`,
-      );
-      return null;
-    }
-    const companyId = booking.companyId;
-    const companyProfileId = booking.companyProfileId ?? null;
-
-    const breakdown = (booking.pricingBreakdown ?? {}) as StoredPricingBreakdown;
-    const currency = breakdown.currency ?? booking.paymentCurrency ?? "ETB";
-    const lines = this.buildLines(breakdown, booking.totalAmount, currency);
-    const subtotal = round2(lines.reduce((sum, l) => sum + l.amount, 0));
-
-    // Honor a staff price override: bill the adjusted total, recording the delta
-    // as an ADJUSTMENT line so the signed lines still sum to the invoice total.
-    const adjusted = booking.adjustedTotalAmount;
-    let total = subtotal;
-    if (adjusted != null && Number.isFinite(Number(adjusted))) {
-      const delta = round2(Number(adjusted) - subtotal);
-      if (delta !== 0) {
-        lines.push({
-          chargeType: "ADJUSTMENT",
-          description: "Staff price adjustment",
-          quantity: 1,
-          unitRate: delta,
-          amount: delta,
-          currency,
-        });
-      }
-      total = round2(Number(adjusted));
-    }
-
-    const issuedAt = new Date();
-    const dueAt = new Date(issuedAt);
-    dueAt.setDate(dueAt.getDate() + DEFAULT_DUE_DAYS);
-
-    return this.dataSource.transaction(async (mg) => {
-      const invoice = await mg.save(
-        mg.create(Invoice, {
-          invoiceNumber: await this.nextInvoiceNumber(mg),
-          companyId,
-          companyProfileId,
-          totalAmount: total,
-          currency,
-          status: Freight.InvoiceStatus.Pending,
-          source: BOOKING_SOURCE,
-          sourceId: bookingId,
-          type: "PREPAID",
-          issuedAt,
-          dueAt,
-        }),
-      );
-
-      for (const line of lines) {
-        await mg.save(mg.create(InvoiceLine, { invoiceId: invoice.id, ...line }));
-      }
-
-      this.logger.log(
-        `Generated invoice ${invoice.invoiceNumber} for booking ${booking.reference} (${total} ${currency}).`,
-      );
-      return invoice;
-    });
-  }
-
-  /** Map the stored pricing line items to invoice lines (one breakdown line → one invoice line). */
-  private buildLines(
-    breakdown: StoredPricingBreakdown,
-    fallbackTotal: number,
-    currency: string,
-  ): BuiltLine[] {
-    const items = breakdown.lineItems ?? [];
-    if (items.length === 0) {
-      // No itemized breakdown — bill a single line for the booking total.
-      return [
-        {
-          chargeType: "FREIGHT",
-          description: "Freight charge",
-          quantity: 1,
-          unitRate: round2(fallbackTotal),
-          amount: round2(fallbackTotal),
-          currency,
-        },
-      ];
-    }
-
-    return items.map((item) => ({
-      chargeType: item.code,
-      description: item.description,
-      quantity: item.quantity,
-      unitRate: round2(item.unitAmount),
-      amount: round2(item.amount),
-      currency: item.currency ?? currency,
-      metadata: { unit: item.unit },
-    }));
-  }
-
   /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */
   private async nextInvoiceNumber(mg: EntityManager): Promise<string> {
     const now = new Date();
@@ -226,108 +116,254 @@ export class BillingService {
     return `${prefix}${String(next).padStart(5, "0")}`;
   }
 
-  // ── Payment reconciliation ───────────────────────────────────────────────────
-
   /**
-   * The invoice a gateway payment should settle for a booking, or null if none.
+   * Generate an invoice for any source (booking, demurrage, manual, …).
    *
-   * This is the billing document of record for "what is owed" — callers (e.g.
-   * `payment.service.initiatePayment`) should charge `invoice.totalAmount` against
-   * it rather than recomputing from `booking.totalAmount`, so discounts/penalties/
-   * adjustments carried on the invoice are honored. Returns the most recent open
-   * (unpaid, non-cancelled) invoice.
+   * Persists the header plus its lines in one transaction and assigns the next
+   * sequential `invoice_number`. The total defaults to the sum of line amounts
+   * unless `totalAmount` is given. Issued invoices (default PENDING) stamp
+   * `issuedAt`; pass `status: DRAFT` to leave it unissued.
+   *
+   * Pass `manager` to enlist in a caller's transaction (e.g. when generating an
+   * invoice as part of a larger booking flow).
    */
-  findPayableForBooking(bookingId: string): Promise<Invoice | null> {
-    return this.dataSource.getRepository(Invoice).findOne({
-      where: {
-        source: BOOKING_SOURCE,
-        sourceId: bookingId,
-        status: In([
-          Freight.InvoiceStatus.Pending,
-          Freight.InvoiceStatus.Draft,
-          Freight.InvoiceStatus.Overdue,
-        ]),
-      },
-      order: { issuedAt: "DESC" },
-    });
-  }
-
-  /**
-   * Mark a booking's paid invoice as refunded. Called from `payment.service.refund`
-   * inside its DB transaction so the invoice tracks the booking/payment reversal.
-   * No-op when the booking has no paid invoice.
-   */
-  async markBookingInvoiceRefunded(
-    bookingId: string,
+  async generateInvoice(
+    input: GenerateInvoiceInput,
     manager?: EntityManager,
-  ): Promise<void> {
-    const mg = manager ?? this.dataSource.manager;
-    const invoice = await mg.findOne(Invoice, {
-      where: {
-        source: BOOKING_SOURCE,
-        sourceId: bookingId,
-        status: Freight.InvoiceStatus.Paid,
-      },
-      order: { issuedAt: "DESC" },
-    });
-    if (!invoice) return;
-
-    await mg.update(
-      Invoice,
-      { id: invoice.id },
-      { status: Freight.InvoiceStatus.Refunded },
-    );
+  ): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const run = (mg: EntityManager) => this.createInvoice(input, mg);
+    return manager ? run(manager) : this.dataSource.transaction(run);
   }
 
-  /**
-   * Mark a booking's open invoice as paid and link the gateway payment.
-   *
-   * Called from `payment.service.finalizePaymentSuccess()` inside its existing DB
-   * transaction (pass the transaction's `EntityManager`). Full-payment only — no
-   * partial settlement in this phase. No-op when the booking has no open invoice.
-   */
-  async markBookingInvoicePaid(
-    bookingId: string,
-    paymentId: string | null,
-    manager?: EntityManager,
-  ): Promise<void> {
-    const mg = manager ?? this.dataSource.manager;
-    const invoice = await mg.findOne(Invoice, {
-      where: {
-        source: BOOKING_SOURCE,
-        sourceId: bookingId,
-        status: In([Freight.InvoiceStatus.Pending, Freight.InvoiceStatus.Draft, Freight.InvoiceStatus.Overdue]),
-      },
-      order: { issuedAt: "DESC" },
-    });
-    if (!invoice) return;
+  private async createInvoice(
+    input: GenerateInvoiceInput,
+    mg: EntityManager,
+  ): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const currency = input.currency ?? "ETB";
+    const status = input.status ?? Freight.InvoiceStatus.Pending;
+    const issued = status !== Freight.InvoiceStatus.Draft;
 
-    await mg.update(
-      Invoice,
-      { id: invoice.id },
-      { status: Freight.InvoiceStatus.Paid, paymentId: paymentId ?? undefined },
+    const lines = input.lines.map((l) => {
+      const quantity = l.quantity ?? 1;
+      const unitRate = l.unitRate ?? 0;
+      return {
+        chargeType: l.chargeType,
+        description: l.description,
+        quantity,
+        unitRate,
+        amount: l.amount ?? quantity * unitRate,
+        currency: l.currency ?? currency,
+        metadata: l.metadata ?? null,
+      };
+    });
+
+    const totalAmount =
+      input.totalAmount ?? lines.reduce((sum, l) => sum + Number(l.amount), 0);
+
+    const dueAt =
+      input.dueAt ??
+      new Date(
+        Date.now() +
+        (input.dueInDays ?? DEFAULT_DUE_DAYS) * 24 * 60 * 60 * 1000,
+      );
+
+    const invoiceNumber = await this.nextInvoiceNumber(mg);
+
+    const invoice = await mg.save(
+      mg.create(Invoice, {
+        invoiceNumber,
+        source: input.source,
+        sourceId: input.sourceId,
+        type: input.type,
+        companyId: input.companyId,
+        companyProfileId: input.companyProfileId,
+        totalAmount,
+        currency,
+        status,
+        issuedAt: issued ? new Date() : null,
+        dueAt,
+      }),
     );
+
+    const savedLines = await Promise.all(
+      lines.map((l) =>
+        mg.save(mg.create(InvoiceLine, { ...l, invoiceId: invoice.id })),
+      ),
+    );
+
+    this.logger.log(
+      `Generated invoice ${invoice.invoiceNumber} (${invoice.id}) for ${input.source}:${input.sourceId}`,
+    );
+
+    return { ...invoice, lines: savedLines };
   }
 
+  // ── State transitions ────────────────────────────────────────────────────────
+
   /**
-   * Single settlement chokepoint for any path that marks a booking PAID: ensure
-   * the booking has an invoice (idempotent generate), then mark it paid. Reused by
-   * the gateway flow and offline/manual "mark paid" so invoicing holds everywhere.
-   *
-   * No-op for bookings that have no invoice and cannot get one (e.g. government
-   * bookings with no company to bill — `generateForBooking` returns null).
+   * Mark an invoice paid and link the gateway payment, then emit
+   * `${source}.invoice.paid`. Full-payment only — no partial settlement.
+   * No-op when the invoice is already paid. Pass `manager` to enlist in a
+   * caller's transaction.
    */
-  async settleBookingInvoice(
-    bookingId: string,
+  async markInvoiceAsPaid(
+    invoiceId: string,
     paymentId: string | null = null,
     manager?: EntityManager,
-  ): Promise<void> {
-    await this.generateForBooking(bookingId);
-    await this.markBookingInvoicePaid(bookingId, paymentId, manager);
+  ): Promise<Invoice | null> {
+    return this.transition(
+      invoiceId,
+      Freight.InvoiceStatus.Paid,
+      "paid",
+      { paymentId: paymentId ?? undefined },
+      manager,
+    );
+  }
+
+  /**
+   * Mark an invoice refunded and emit `${source}.invoice.refunded`.
+   * No-op when already refunded.
+   */
+  async markInvoiceAsRefunded(
+    invoiceId: string,
+    manager?: EntityManager,
+  ): Promise<Invoice | null> {
+    return this.transition(
+      invoiceId,
+      Freight.InvoiceStatus.Refunded,
+      "refunded",
+      {},
+      manager,
+    );
+  }
+
+  /**
+   * Mark an invoice cancelled and emit `${source}.invoice.cancelled`.
+   * No-op when already cancelled.
+   */
+  async cancelInvoice(
+    invoiceId: string,
+    manager?: EntityManager,
+  ): Promise<Invoice | null> {
+    return this.transition(
+      invoiceId,
+      Freight.InvoiceStatus.Cancelled,
+      "cancelled",
+      {},
+      manager,
+    );
+  }
+
+  /**
+   * Load the invoice, apply the new status (+ extra columns), then emit
+   * `${source}.invoice.<event>`. No-op (returns the invoice) when it is already
+   * in the target status. Throws when the invoice does not exist.
+   *
+   * Note: the event fires in-process synchronously. When a `manager` from an
+   * outer transaction is passed, listeners run before that transaction commits.
+   */
+  private async transition(
+    invoiceId: string,
+    status: Freight.InvoiceStatus,
+    event: string,
+    extra: { paymentId?: string },
+    manager?: EntityManager,
+  ): Promise<Invoice | null> {
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    if (invoice.status === status) return invoice;
+
+    await mg.update(Invoice, { id: invoice.id }, { status, ...extra });
+
+    const updated = { ...invoice, ...extra, status } as Invoice;
+    this.emitInvoiceEvent(event, updated);
+    return updated;
+  }
+
+  /** Broadcast `${invoice.source}.invoice.<event>` to in-process listeners. */
+  private emitInvoiceEvent(event: string, invoice: Invoice): void {
+    const payload: InvoiceEventPayload = {
+      invoiceId: invoice.id,
+      invoiceNumber: invoice.invoiceNumber,
+      source: invoice.source as Freight.InvoiceSource,
+      sourceId: invoice.sourceId,
+      type: invoice.type,
+      companyId: invoice.companyId,
+      companyProfileId: invoice.companyProfileId,
+      totalAmount: invoice.totalAmount,
+      currency: invoice.currency,
+      status: invoice.status,
+      paymentId: invoice.paymentId ?? null,
+    };
+    this.events.emit(`${invoice.source}.invoice.${event}`, payload);
+  }
+
+  // ── Payment reconciliation (by source) ───────────────────────────────────────
+
+  /**
+   * The invoice a gateway payment should settle for a source record, or null if
+   * none. This is the billing document of record for "what is owed" — callers
+   * (e.g. `payment.service.initiatePayment`) should charge `invoice.totalAmount`
+   * against it rather than recomputing from the source's own total, so
+   * discounts/penalties/adjustments carried on the invoice are honored. Returns
+   * the most recent open (unpaid, non-cancelled) invoice.
+   */
+  findPayable(
+    source: Freight.InvoiceSource,
+    sourceId: string,
+  ): Promise<Invoice | null> {
+    return this.dataSource.getRepository(Invoice).findOne({
+      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      order: { issuedAt: "DESC" },
+    });
+  }
+
+  /**
+   * Settle a source's open invoice as paid and link the gateway payment, then
+   * emit `${source}.invoice.paid`. Resolves the open invoice via {@link findPayable}
+   * then delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
+   * settlement. No-op (returns null) when the source has no open invoice.
+   *
+   * Pass the caller's transaction `manager` (e.g. from
+   * `payment.service.finalizePaymentSuccess`) to enlist in its DB transaction.
+   */
+  async settlePayable(
+    source: Freight.InvoiceSource,
+    sourceId: string,
+    paymentId: string | null,
+    manager?: EntityManager,
+  ): Promise<Invoice | null> {
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, {
+      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      order: { issuedAt: "DESC" },
+    });
+    if (!invoice) return null;
+
+    return this.markInvoiceAsPaid(invoice.id, paymentId, mg);
+  }
+
+  /**
+   * Refund a source's paid invoice, then emit `${source}.invoice.refunded`.
+   * Resolves the paid invoice then delegates to {@link markInvoiceAsRefunded}.
+   * No-op (returns null) when the source has no paid invoice.
+   *
+   * Pass the caller's transaction `manager` (e.g. from `payment.service.refund`)
+   * to enlist in its DB transaction.
+   */
+  async refundPayable(
+    source: Freight.InvoiceSource,
+    sourceId: string,
+    manager?: EntityManager,
+  ): Promise<Invoice | null> {
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, {
+      where: { source, sourceId, status: Freight.InvoiceStatus.Paid },
+      order: { issuedAt: "DESC" },
+    });
+    if (!invoice) return null;
+
+    return this.markInvoiceAsRefunded(invoice.id, mg);
   }
 }
-
-/** Round to 2 decimal places without float drift. */
-function round2(n: number): number {
-  return Math.round(Number(n) * 100) / 100;
-}
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 040848021..374eee28a 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -137,6 +137,14 @@ export enum InvoiceStatus {
   Refunded = "REFUNDED",
 }
 
+/** Originating subsystem an invoice bills for; namespaces invoice events. */
+export enum InvoiceSource {
+  Booking = "booking",
+  Contract = "contract",
+  Warehouse = "warehouse",
+  Demurrage = "demurrage",
+}
+
 export enum SchedulingStatus {
   NotScheduled = "NOT_SCHEDULED",
   Holding = "HOLDING",

From 1da5af94ab3c7f569ca8509baae07c5776dde681 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 07:32:42 +0000
Subject: [PATCH 08/63] feat: scoped the payables by type

---
 .../modules/billing/billing.service.spec.ts   |  2 ++
 .../src/modules/billing/billing.service.ts    | 35 ++++++++++++-------
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 62b3cebaa..767aabec8 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -160,6 +160,7 @@ describe("BillingService.settlePayable", () => {
     const settled = await service.settlePayable(
       Freight.InvoiceSource.Booking,
       "booking-1",
+      Freight.InvoiceType.Prepaid,
       "pay-1",
       mg as never,
     );
@@ -184,6 +185,7 @@ describe("BillingService.settlePayable", () => {
     const settled = await service.settlePayable(
       Freight.InvoiceSource.Booking,
       "booking-1",
+      Freight.InvoiceType.Prepaid,
       "pay-1",
       mg as never,
     );
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index ff41eb4e6..f79548266 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -306,37 +306,44 @@ export class BillingService {
    * none. This is the billing document of record for "what is owed" — callers
    * (e.g. `payment.service.initiatePayment`) should charge `invoice.totalAmount`
    * against it rather than recomputing from the source's own total, so
-   * discounts/penalties/adjustments carried on the invoice are honored. Returns
-   * the most recent open (unpaid, non-cancelled) invoice.
+   * discounts/penalties/adjustments carried on the invoice are honored.
+   *
+   * `type` selects which invoice when a source carries several (e.g. a booking's
+   * up-front vs final charge). Returns the most recent open (unpaid,
+   * non-cancelled) invoice of that type.
    */
   findPayable(
     source: Freight.InvoiceSource,
     sourceId: string,
+    type: string,
   ): Promise<Invoice | null> {
     return this.dataSource.getRepository(Invoice).findOne({
-      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      where: { source, sourceId, type, status: In(OPEN_STATUSES) },
       order: { issuedAt: "DESC" },
     });
   }
 
   /**
-   * Settle a source's open invoice as paid and link the gateway payment, then
-   * emit `${source}.invoice.paid`. Resolves the open invoice via {@link findPayable}
-   * then delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
-   * settlement. No-op (returns null) when the source has no open invoice.
+   * Settle a source's open invoice of `type` as paid and link the gateway
+   * payment, then emit `${source}.invoice.paid`. Resolves the open invoice then
+   * delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
+   * settlement. No-op (returns null) when the source has no open invoice of that
+   * type.
    *
-   * Pass the caller's transaction `manager` (e.g. from
+   * `type` selects which invoice when a source carries several (e.g. a booking's
+   * up-front vs final charge). Pass the caller's transaction `manager` (e.g. from
    * `payment.service.finalizePaymentSuccess`) to enlist in its DB transaction.
    */
   async settlePayable(
     source: Freight.InvoiceSource,
     sourceId: string,
+    type: string,
     paymentId: string | null,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      where: { source, sourceId, type, status: In(OPEN_STATUSES) },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return null;
@@ -345,9 +352,10 @@ export class BillingService {
   }
 
   /**
-   * Refund a source's paid invoice, then emit `${source}.invoice.refunded`.
-   * Resolves the paid invoice then delegates to {@link markInvoiceAsRefunded}.
-   * No-op (returns null) when the source has no paid invoice.
+   * Refund a source's paid invoice of `type`, then emit
+   * `${source}.invoice.refunded`. Resolves the paid invoice then delegates to
+   * {@link markInvoiceAsRefunded}. No-op (returns null) when the source has no
+   * paid invoice of that type.
    *
    * Pass the caller's transaction `manager` (e.g. from `payment.service.refund`)
    * to enlist in its DB transaction.
@@ -355,11 +363,12 @@ export class BillingService {
   async refundPayable(
     source: Freight.InvoiceSource,
     sourceId: string,
+    type: string,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: Freight.InvoiceStatus.Paid },
+      where: { source, sourceId, type, status: Freight.InvoiceStatus.Paid },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return null;

From 36711eace4abc5aa41b1c9494da8cc5365024473 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 08:28:12 +0000
Subject: [PATCH 09/63] chore: type updates on the billing service

---
 .../modules/billing/billing.service.spec.ts   | 67 +++++++++++++++----
 .../src/modules/billing/billing.service.ts    | 39 ++++++-----
 2 files changed, 76 insertions(+), 30 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 767aabec8..72ddb0b02 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -33,8 +33,20 @@ function generateInput(overrides: Record<string, unknown> = {}) {
     companyProfileId: "profile-1",
     currency: "ETB",
     lines: [
-      { chargeType: "RAIL_FREIGHT", description: "Rail freight", quantity: 2, unitRate: 500, amount: 1000 },
-      { chargeType: "HAZARD_SURCHARGE", description: "Hazard surcharge", quantity: 2, unitRate: 250, amount: 500 },
+      {
+        chargeType: "RAIL_FREIGHT",
+        description: "Rail freight",
+        quantity: 2,
+        unitRate: 500,
+        amount: 1000,
+      },
+      {
+        chargeType: "HAZARD_SURCHARGE",
+        description: "Hazard surcharge",
+        quantity: 2,
+        unitRate: 250,
+        amount: 500,
+      },
     ],
     ...overrides,
   };
@@ -52,10 +64,17 @@ describe("BillingService.generateInvoice", () => {
     manager = makeManager(savedLines);
     events = makeEvents();
     dataSource = {
-      transaction: jest.fn().mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
+      transaction: jest
+        .fn()
+        .mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
       manager,
     };
-    service = new BillingService(dataSource as never, {} as never, {} as never, events as never);
+    service = new BillingService(
+      dataSource as never,
+      {} as never,
+      {} as never,
+      events as never,
+    );
   });
 
   it("creates a PENDING invoice with one line per input line", async () => {
@@ -122,18 +141,31 @@ describe("BillingService.markInvoiceAsPaid", () => {
     );
     expect(events.emit).toHaveBeenCalledWith(
       "booking.invoice.paid",
-      expect.objectContaining({ invoiceId: "inv-1", status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" }),
+      expect.objectContaining({
+        invoiceId: "inv-1",
+        status: Freight.InvoiceStatus.Paid,
+        paymentId: "pay-1",
+      }),
     );
   });
 
   it("is a no-op (no event) when the invoice is already paid", async () => {
-    const paid = { id: "inv-1", status: Freight.InvoiceStatus.Paid, source: "booking" };
+    const paid = {
+      id: "inv-1",
+      status: Freight.InvoiceStatus.Paid,
+      source: "booking",
+    };
     const mg = {
       findOne: jest.fn().mockResolvedValue(paid),
       update: jest.fn().mockResolvedValue(undefined),
     };
     const events = makeEvents();
-    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
+    const service = new BillingService(
+      { manager: mg } as never,
+      {} as never,
+      {} as never,
+      events as never,
+    );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
 
@@ -155,12 +187,16 @@ describe("BillingService.settlePayable", () => {
       update: jest.fn().mockResolvedValue(undefined),
     };
     const events = makeEvents();
-    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
+    const service = new BillingService(
+      { manager: mg } as never,
+      {} as never,
+      {} as never,
+      events as never,
+    );
 
     const settled = await service.settlePayable(
       Freight.InvoiceSource.Booking,
       "booking-1",
-      Freight.InvoiceType.Prepaid,
       "pay-1",
       mg as never,
     );
@@ -171,7 +207,10 @@ describe("BillingService.settlePayable", () => {
       { id: "inv-1" },
       { status: Freight.InvoiceStatus.Paid, paymentId: "pay-1" },
     );
-    expect(events.emit).toHaveBeenCalledWith("booking.invoice.paid", expect.anything());
+    expect(events.emit).toHaveBeenCalledWith(
+      "booking.invoice.paid",
+      expect.anything(),
+    );
   });
 
   it("is a no-op (returns null) when the source has no open invoice", async () => {
@@ -180,12 +219,16 @@ describe("BillingService.settlePayable", () => {
       update: jest.fn().mockResolvedValue(undefined),
     };
     const events = makeEvents();
-    const service = new BillingService({ manager: mg } as never, {} as never, {} as never, events as never);
+    const service = new BillingService(
+      { manager: mg } as never,
+      {} as never,
+      {} as never,
+      events as never,
+    );
 
     const settled = await service.settlePayable(
       Freight.InvoiceSource.Booking,
       "booking-1",
-      Freight.InvoiceType.Prepaid,
       "pay-1",
       mg as never,
     );
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index f79548266..b1e3d25bf 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -308,42 +308,47 @@ export class BillingService {
    * against it rather than recomputing from the source's own total, so
    * discounts/penalties/adjustments carried on the invoice are honored.
    *
-   * `type` selects which invoice when a source carries several (e.g. a booking's
-   * up-front vs final charge). Returns the most recent open (unpaid,
-   * non-cancelled) invoice of that type.
+   * Pass `type` to select a specific invoice when a source carries several (e.g.
+   * a booking's up-front vs final charge); omit it to settle whichever single
+   * invoice is currently open. Returns the most recent matching open (unpaid,
+   * non-cancelled) invoice.
    */
   findPayable(
     source: Freight.InvoiceSource,
     sourceId: string,
-    type: string,
+    type?: string,
   ): Promise<Invoice | null> {
     return this.dataSource.getRepository(Invoice).findOne({
-      where: { source, sourceId, type, status: In(OPEN_STATUSES) },
+      where: {
+        source,
+        sourceId,
+        status: In(OPEN_STATUSES),
+        ...(type ? { type } : {}),
+      },
       order: { issuedAt: "DESC" },
     });
   }
 
   /**
-   * Settle a source's open invoice of `type` as paid and link the gateway
+   * Settle a source's currently-open invoice as paid and link the gateway
    * payment, then emit `${source}.invoice.paid`. Resolves the open invoice then
    * delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
-   * settlement. No-op (returns null) when the source has no open invoice of that
-   * type.
+   * settlement. No-op (returns null) when the source has no open invoice.
    *
-   * `type` selects which invoice when a source carries several (e.g. a booking's
-   * up-front vs final charge). Pass the caller's transaction `manager` (e.g. from
+   * Type-blind by design: the payment process settles whichever invoice is due;
+   * any per-type reaction belongs in the `${source}.invoice.paid` handler, which
+   * reads `invoice.type`. Pass the caller's transaction `manager` (e.g. from
    * `payment.service.finalizePaymentSuccess`) to enlist in its DB transaction.
    */
   async settlePayable(
     source: Freight.InvoiceSource,
     sourceId: string,
-    type: string,
     paymentId: string | null,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, type, status: In(OPEN_STATUSES) },
+      where: { source, sourceId, status: In(OPEN_STATUSES) },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return null;
@@ -352,10 +357,9 @@ export class BillingService {
   }
 
   /**
-   * Refund a source's paid invoice of `type`, then emit
-   * `${source}.invoice.refunded`. Resolves the paid invoice then delegates to
-   * {@link markInvoiceAsRefunded}. No-op (returns null) when the source has no
-   * paid invoice of that type.
+   * Refund a source's paid invoice, then emit `${source}.invoice.refunded`.
+   * Resolves the paid invoice then delegates to {@link markInvoiceAsRefunded}.
+   * No-op (returns null) when the source has no paid invoice.
    *
    * Pass the caller's transaction `manager` (e.g. from `payment.service.refund`)
    * to enlist in its DB transaction.
@@ -363,12 +367,11 @@ export class BillingService {
   async refundPayable(
     source: Freight.InvoiceSource,
     sourceId: string,
-    type: string,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, type, status: Freight.InvoiceStatus.Paid },
+      where: { source, sourceId, status: Freight.InvoiceStatus.Paid },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return null;

From 9cd24d9b519c85b98a4957eeca520754fea36845 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 08:29:07 +0000
Subject: [PATCH 10/63] feat(WIP): Wire up the invoice with the booking.

---
 .../bookings/booking-invoice.service.ts       | 152 ++++++++++++++++++
 .../booking-transition.accept.spec.ts         |   1 +
 .../booking-transition.clearance.spec.ts      |   3 +
 .../booking-transition.operation.spec.ts      |   1 +
 .../bookings/booking-transition.service.ts    |  22 ++-
 .../src/modules/bookings/bookings.module.ts   |   4 +
 .../src/modules/payment/payment.module.ts     |   2 +
 .../src/modules/payment/payment.service.ts    |  25 ++-
 8 files changed, 208 insertions(+), 2 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
new file mode 100644
index 000000000..daa3327dd
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
@@ -0,0 +1,152 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Freight } from '@edr/types';
+
+import {
+  BillingService,
+  GenerateInvoiceInput,
+  InvoiceEventPayload,
+  InvoiceLineInput,
+} from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { PriceLineItemDto } from './dto/generate-price-response.dto';
+import { Booking } from './entities/booking.entity';
+
+/** Snapshot written onto `booking.pricingBreakdown` by the pricing service. */
+interface StoredPricingBreakdown {
+  lineItems?: PriceLineItemDto[];
+  totalAmount?: number;
+  currency?: string;
+}
+
+/** Round to 2 decimals, avoiding binary float drift. */
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+/**
+ * Owns the booking ⇄ invoice mapping — the one place that knows how a booking
+ * turns into invoices and which type to use. Bookings are the billable business
+ * entity, so they generate their own invoices directly via {@link BillingService}
+ * (billing stays source-agnostic). All booking-specific type branching lives here,
+ * at the two points it belongs: invoice creation and settlement (the paid handler).
+ */
+@Injectable()
+export class BookingInvoiceService {
+  private readonly logger = new Logger(BookingInvoiceService.name);
+
+  constructor(private readonly billing: BillingService) {}
+
+  /**
+   * Ensure the booking has its invoice, generating one from the snapshotted
+   * pricing breakdown if absent. Called when a booking reaches a billable state.
+   * Idempotent — returns the existing open invoice instead of a duplicate.
+   * Returns `null` (and logs) when the booking is not billable: no company to
+   * bill (e.g. government bookings whose `companyId` is null, which the invoices
+   * FK requires), or no priced amount.
+   */
+  async ensureInvoiceForBooking(booking: Booking): Promise<Invoice | null> {
+    const existing = await this.billing.findPayable(
+      Freight.InvoiceSource.Booking,
+      booking.id,
+      Freight.InvoiceType.Prepaid,
+    );
+    if (existing) return existing;
+
+    if (!booking.companyId) {
+      this.logger.warn(
+        `Skipping invoice for booking ${booking.reference} (${booking.id}): no company to bill.`,
+      );
+      return null;
+    }
+
+    const input = this.buildInput(booking);
+    if (!input) {
+      this.logger.warn(
+        `Skipping invoice for booking ${booking.reference} (${booking.id}): no priced amount.`,
+      );
+      return null;
+    }
+
+    return this.billing.generateInvoice(input);
+  }
+
+  /**
+   * React to a booking invoice being paid — the settlement branch point. Per-type
+   * reactions live here (not in the payment process): e.g. a paid up-front invoice
+   * may later generate a final invoice. Only PREPAID exists today.
+   */
+  @OnEvent('booking.invoice.paid')
+  onBookingInvoicePaid(payload: InvoiceEventPayload): void {
+    switch (payload.type) {
+      case Freight.InvoiceType.Prepaid:
+        // Full prepaid settlement — booking advancement is handled by the
+        // payment flow today. Final-invoice issuance would hook in here.
+        break;
+      default:
+        this.logger.warn(
+          `Unhandled booking invoice type "${payload.type}" paid (${payload.invoiceId})`,
+        );
+    }
+  }
+
+  /** Map a booking's pricing snapshot into a generic invoice request. */
+  private buildInput(booking: Booking): GenerateInvoiceInput | null {
+    const breakdown = (booking.pricingBreakdown ?? {}) as StoredPricingBreakdown;
+    const currency = breakdown.currency ?? booking.paymentCurrency ?? 'ETB';
+
+    const lines: InvoiceLineInput[] = (breakdown.lineItems ?? []).map((l) => ({
+      chargeType: l.code,
+      description: l.description,
+      quantity: l.quantity,
+      unitRate: l.unitAmount,
+      amount: l.amount,
+      currency: l.currency ?? currency,
+      metadata: l.unit ? { unit: l.unit } : null,
+    }));
+
+    // Fall back to a single freight line when no breakdown was snapshotted.
+    if (lines.length === 0) {
+      const amount = Number(booking.totalAmount);
+      if (!Number.isFinite(amount) || amount <= 0) return null;
+      lines.push({
+        chargeType: 'FREIGHT',
+        description: 'Rail freight',
+        quantity: 1,
+        unitRate: amount,
+        amount,
+        currency,
+      });
+    }
+
+    const subtotal = round2(lines.reduce((sum, l) => sum + Number(l.amount), 0));
+    let totalAmount = subtotal;
+
+    // Honor a staff price override: bill the adjusted total, recording the delta
+    // as an ADJUSTMENT line so the lines still sum to the invoice total.
+    const adjusted = booking.adjustedTotalAmount;
+    if (adjusted != null && Number.isFinite(Number(adjusted))) {
+      const delta = round2(Number(adjusted) - subtotal);
+      if (delta !== 0) {
+        lines.push({
+          chargeType: 'ADJUSTMENT',
+          description: 'Staff price adjustment',
+          quantity: 1,
+          unitRate: delta,
+          amount: delta,
+          currency,
+        });
+      }
+      totalAmount = round2(Number(adjusted));
+    }
+
+    return {
+      source: Freight.InvoiceSource.Booking,
+      sourceId: booking.id,
+      type: Freight.InvoiceType.Prepaid,
+      companyId: booking.companyId,
+      companyProfileId: booking.companyProfileId,
+      currency,
+      lines,
+      totalAmount,
+    };
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts
index 676d1b5d4..a9806f1f7 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts
@@ -30,6 +30,7 @@ describe('BookingTransitionService — acceptIntake validity window', () => {
       ruleEngineService as never,
       {} as never, // pricingService
       {} as never, // contractService
+      {} as never, // invoiceService
       {} as never, // filesService
       {} as never, // fileUploadSettingsService
       {} as never, // bookingBatchService
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts
index f9c7e182f..ff08784a6 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts
@@ -41,6 +41,7 @@ describe('BookingTransitionService — finalizeClearance gate', () => {
       {} as never, // ruleEngineService
       {} as never, // pricingService
       {} as never, // contractService
+      {} as never, // invoiceService
       filesService as never,
       fileUploadSettingsService as never,
       {} as never, // bookingBatchService
@@ -122,6 +123,7 @@ describe('BookingTransitionService — finalizeClearance customs output gate', (
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // invoiceService
       filesService as never,
       fileUploadSettingsService as never,
       {} as never,
@@ -189,6 +191,7 @@ describe('BookingTransitionService — submitClearanceDocuments required-fields
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // invoiceService
       filesService as never,
       fileUploadSettingsService as never,
       {} as never,
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts
index 92ab8769e..3feac4e67 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts
@@ -34,6 +34,7 @@ describe('BookingTransitionService — operation review', () => {
       {} as never, // ruleEngineService
       {} as never, // pricingService
       {} as never, // contractService
+      {} as never, // invoiceService
       {} as never, // filesService
       {} as never, // fileUploadSettingsService
       bookingBatchService as never,
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index d819ee527..1b6ddd100 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -3,6 +3,7 @@ import {
   forwardRef,
   Inject,
   Injectable,
+  Logger,
 } from '@nestjs/common';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 
@@ -14,6 +15,7 @@ import { RuleEngineService } from '../rule-engine/rule-engine.service';
 import { FilesService } from '../files/files.service';
 import { FileUploadSettingsService } from '../file-upload-settings/file-upload-settings.service';
 import { BookingContractService } from './booking-contract.service';
+import { BookingInvoiceService } from './booking-invoice.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingsRepository } from './bookings.repository';
 import { assertBookingStatus } from './booking-status.util';
@@ -26,11 +28,14 @@ import { BookingsService } from './bookings.service';
 
 @Injectable()
 export class BookingTransitionService {
+  private readonly logger = new Logger(BookingTransitionService.name);
+
   constructor(
     private readonly bookingsRepository: BookingsRepository,
     private readonly ruleEngineService: RuleEngineService,
     private readonly pricingService: BookingPricingService,
     private readonly contractService: BookingContractService,
+    private readonly invoiceService: BookingInvoiceService,
     private readonly filesService: FilesService,
     private readonly fileUploadSettingsService: FileUploadSettingsService,
     @Inject(forwardRef(() => BookingBatchService))
@@ -404,7 +409,22 @@ export class BookingTransitionService {
       marketingApprovedAt: new Date(),
       lockedAt: new Date(),
     } as never);
-    return this.bookingsService.findById(updated!.id);
+
+    const executed = await this.bookingsService.findById(updated!.id);
+
+    // Billable state reached — generate the invoice payment will settle.
+    // Non-blocking: a billing hiccup must not undo the execution.
+    await this.invoiceService
+      .ensureInvoiceForBooking(executed)
+      .catch((err) =>
+        this.logger.error(
+          `Failed to generate invoice for booking ${executed.reference}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        ),
+      );
+
+    return executed;
   }
 
   async startTransit(bookingId: string): Promise<Booking> {
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index ded7d0239..8318a4e7d 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -10,7 +10,9 @@ import { MinioModule } from '../minio/minio.module';
 import { RuleEngineModule } from '../rule-engine/rule-engine.module';
 import { FileUploadSettingsModule } from '../file-upload-settings/file-upload-settings.module';
 import { SignaturesModule } from '../signatures/signatures.module';
+import { BillingModule } from '../billing/billing.module';
 import { BookingContractService } from './booking-contract.service';
+import { BookingInvoiceService } from './booking-invoice.service';
 import { BookingPaymentService } from './booking-payment.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingReferenceDataService } from './booking-reference-data.service';
@@ -49,6 +51,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
       BookingContractSignature,
     ]),
     PaymentModule,
+    BillingModule,
     forwardRef(() => TrainSchedulingModule),
     FilesModule,
     MinioModule,
@@ -72,6 +75,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
     BookingPricingService,
     BookingTransitionService,
     BookingContractService,
+    BookingInvoiceService,
     BookingPaymentService,
     ContractTemplateResolver,
     ContractViewModelBuilder,
diff --git a/apps/edr-freight-api/src/modules/payment/payment.module.ts b/apps/edr-freight-api/src/modules/payment/payment.module.ts
index c48f1fac9..18e32330d 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.module.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.module.ts
@@ -12,6 +12,7 @@ import {
 } from "@edr/types";
 
 import { ServiceAuthGuard } from "../../common/guards/service-auth.guard";
+import { BillingModule } from "../billing/billing.module";
 import { DropdownSettingsModule } from "../dropdown-settings/dropdown-settings.module";
 import { FirstMileModule } from "../first-mile/first-mile.module";
 import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.module";
@@ -59,6 +60,7 @@ function rabbitMQImport(): DynamicModule[] {
         HttpModule.register({ timeout: 10_000 }),
         ConfigModule,
         DropdownSettingsModule,
+        BillingModule,
         forwardRef(() => FirstMileModule),
         forwardRef(() => TrainSchedulingModule),
         TypeOrmModule.forFeature([
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 582e7467e..5fb77f404 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -22,11 +22,13 @@ import {
     ProviderPaymentStatus,
 } from "@edr/payment-providers";
 import {
+    Freight,
     PaymentService as PaymentServiceEnum,
     PaymentReferenceType,
     PaymentIntentSnapshot,
     ProviderMethod,
 } from "@edr/types";
+import { BillingService } from "../billing/billing.service";
 import {
     InitiatePaymentDto,
     InitiateResponseDto,
@@ -62,6 +64,7 @@ export class PaymentService {
         private readonly bookingBatchService: BookingBatchService,
         private readonly dropdownSettings: DropdownSettingsService,
         private readonly firstMileService: FirstMileService,
+        private readonly billing: BillingService,
     ) { }
 
     /** Configured general-contract ordering window in months (defaults to 3). */
@@ -167,7 +170,16 @@ export class PaymentService {
             .findOneBy({ id: dto.bookingId });
         if (!booking) throw new NotFoundException("Booking not found");
 
-        const amountMinor = Math.round(Number(booking.totalAmount));
+        // Charge the invoice (the billing document of record) so discounts,
+        // penalties and staff adjustments carried on it are honored. Fall back to
+        // the booking total only when no invoice has been generated yet.
+        const invoice = await this.billing.findPayable(
+            Freight.InvoiceSource.Booking,
+            booking.id,
+        );
+        const amountMinor = Math.round(
+            Number(invoice?.totalAmount ?? booking.totalAmount),
+        );
 
         const snapshot = await this.paymentClient.initiate({
             service: PaymentServiceEnum.FREIGHT,
@@ -344,6 +356,17 @@ export class PaymentService {
                     ? { paymentStatus: "PAID", status: "CONTRACT_ACTIVE", expiresAt: contractExpiresAt }
                     : { paymentStatus: "PAID", status: "PAID" },
             );
+
+            // Settle the booking's open invoice in the same transaction and link
+            // this payment. The invoice emits `booking.invoice.paid` for the source
+            // to react to. No-op if the booking has no open invoice.
+            await this.billing.settlePayable(
+                Freight.InvoiceSource.Booking,
+                input.bookingId,
+                intent.id,
+                mg,
+            );
+
                         await this.firstMileService.acceptBooking(input.bookingId);
 
         });

From 4be4286fbf193b9b58e3d3e0717a92588040d9fe Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 09:25:46 +0000
Subject: [PATCH 11/63] feat: rewired up the billing and payment with the
 booking

---
 .../src/modules/billing/billing.controller.ts |   2 +-
 .../src/modules/billing/billing.module.ts     |   8 +-
 .../modules/billing/billing.service.spec.ts   |   5 +
 .../src/modules/billing/billing.service.ts    | 102 ++++-
 .../bookings/booking-invoice.service.ts       | 104 ++++-
 .../bookings/booking-payment.controller.ts    | 180 +++++++++
 .../bookings/booking-payment.service.ts       |  34 +-
 .../src/modules/bookings/bookings.module.ts   |   9 +-
 .../src/modules/payment/payment.controller.ts | 143 +------
 .../src/modules/payment/payment.module.ts     |  10 +-
 .../src/modules/payment/payment.service.ts    | 358 +++++++++---------
 packages/types/src/freight/index.ts           |   9 +-
 12 files changed, 584 insertions(+), 380 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-payment.controller.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index e7ac41704..e954b7e1b 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -1,4 +1,4 @@
-import { Controller, Get, Param, ParseUUIDPipe, Post } from "@nestjs/common";
+import { Controller, Get, Param, ParseUUIDPipe } from "@nestjs/common";
 import { ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import { FreightAdmin } from "../../common/booking-guards";
diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 1dd745088..1ed135bbb 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -1,4 +1,4 @@
-import { Module } from "@nestjs/common";
+import { forwardRef, Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { BillingController } from "./billing.controller";
@@ -7,9 +7,13 @@ import { Invoice } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
+import { PaymentModule } from "../payment/payment.module";
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Invoice, InvoiceLine])],
+  imports: [
+    TypeOrmModule.forFeature([Invoice, InvoiceLine]),
+    forwardRef(() => PaymentModule),
+  ],
   controllers: [BillingController],
   providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
   exports: [BillingService],
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 72ddb0b02..907aeb76d 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -74,6 +74,7 @@ describe("BillingService.generateInvoice", () => {
       {} as never,
       {} as never,
       events as never,
+      {} as never, // payment
     );
   });
 
@@ -130,6 +131,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never,
       {} as never,
       events as never,
+      {} as never, // payment
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -165,6 +167,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never,
       {} as never,
       events as never,
+      {} as never, // payment
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -192,6 +195,7 @@ describe("BillingService.settlePayable", () => {
       {} as never,
       {} as never,
       events as never,
+      {} as never, // payment
     );
 
     const settled = await service.settlePayable(
@@ -224,6 +228,7 @@ describe("BillingService.settlePayable", () => {
       {} as never,
       {} as never,
       events as never,
+      {} as never, // payment
     );
 
     const settled = await service.settlePayable(
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index b1e3d25bf..448ad6685 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,4 +1,4 @@
-import { Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { forwardRef, Inject, Injectable, Logger, NotFoundException } from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
 import { Freight } from "@edr/types";
 import { DataSource, EntityManager, In } from "typeorm";
@@ -7,6 +7,8 @@ import { Invoice } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
+import { PaymentService } from "../payment/payment.service";
+import { InitiateResponseDto } from "../payment/payments.dto";
 
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
 const DEFAULT_DUE_DAYS = 14;
@@ -80,6 +82,8 @@ export class BillingService {
     private readonly invoices: InvoiceRepository,
     private readonly invoiceLines: InvoiceLineRepository,
     private readonly events: EventEmitter2,
+    @Inject(forwardRef(() => PaymentService))
+    private readonly payment: PaymentService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -304,9 +308,9 @@ export class BillingService {
   /**
    * The invoice a gateway payment should settle for a source record, or null if
    * none. This is the billing document of record for "what is owed" — callers
-   * (e.g. `payment.service.initiatePayment`) should charge `invoice.totalAmount`
-   * against it rather than recomputing from the source's own total, so
-   * discounts/penalties/adjustments carried on the invoice are honored.
+   * (e.g. {@link payInvoice}) charge `invoice.totalAmount` against it rather than
+   * recomputing from the source's own total, so discounts/penalties/adjustments
+   * carried on the invoice are honored.
    *
    * Pass `type` to select a specific invoice when a source carries several (e.g.
    * a booking's up-front vs final charge); omit it to settle whichever single
@@ -335,10 +339,13 @@ export class BillingService {
    * delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
    * settlement. No-op (returns null) when the source has no open invoice.
    *
-   * Type-blind by design: the payment process settles whichever invoice is due;
-   * any per-type reaction belongs in the `${source}.invoice.paid` handler, which
-   * reads `invoice.type`. Pass the caller's transaction `manager` (e.g. from
-   * `payment.service.finalizePaymentSuccess`) to enlist in its DB transaction.
+   * Type-blind by design: settles whichever invoice is due; any per-type reaction
+   * belongs in the `${source}.invoice.paid` handler, which reads `invoice.type`.
+   * Pass the caller's transaction `manager` to enlist in its DB transaction.
+   *
+   * NOTE: the booking flow settles via {@link payInvoice} + the `payment.succeeded`
+   * event ({@link settleByPaymentId}); this source-keyed settle is a generic helper
+   * for callers that settle by source rather than by gateway intent id.
    */
   async settlePayable(
     source: Freight.InvoiceSource,
@@ -378,4 +385,83 @@ export class BillingService {
 
     return this.markInvoiceAsRefunded(invoice.id, mg);
   }
+
+  // ── Payment initiation & settlement (the gateway boundary) ───────────────────
+
+  /**
+   * Charge a source's open invoice through the payment gateway. Billing is the
+   * single place that turns "what is owed" (the invoice) into a payment intent —
+   * the domain never talks to the payment service directly. Resolves the open
+   * invoice, opens an intent for `invoice.totalAmount`, records the intent id on
+   * the invoice (the settlement correlation key), and returns the client action.
+   *
+   * When the provider settles synchronously, the invoice is settled inline here —
+   * after the intent id is stored — so the `payment.succeeded` correlation can
+   * never fire before the link exists. Throws when the source has no open invoice.
+   */
+  async payInvoice(
+    source: Freight.InvoiceSource,
+    sourceId: string,
+    opts: {
+      method?: string;
+      platform?: "web" | "mobile";
+      payerAccount?: string;
+      returnUrl?: string;
+      failureUrl?: string;
+    } = {},
+  ): Promise<InitiateResponseDto> {
+    const invoice = await this.findPayable(source, sourceId);
+    if (!invoice) {
+      throw new NotFoundException(`No open invoice to charge for ${source}:${sourceId}`);
+    }
+
+    const result = await this.payment.initiate({
+      referenceId: sourceId,
+      orderRef: invoice.invoiceNumber,
+      amountMinor: Math.round(Number(invoice.totalAmount)),
+      currency: invoice.currency,
+      reason: `Payment for invoice ${invoice.invoiceNumber}`,
+      method: opts.method ?? "TELEBIRR",
+      platform: opts.platform,
+      payerAccount: opts.payerAccount,
+      returnUrl: opts.returnUrl,
+      failureUrl: opts.failureUrl,
+    });
+
+    // Link the intent to the invoice BEFORE any settlement can correlate against it.
+    await this.dataSource
+      .getRepository(Invoice)
+      .update({ id: invoice.id }, { paymentId: result.intentId });
+
+    if (result.immediateSuccess) {
+      await this.settleByPaymentId(
+        result.intentId,
+        result.providerTxnId,
+        result.paidAt,
+      );
+    }
+
+    return result.response;
+  }
+
+  /**
+   * Settle the open invoice linked to a gateway intent id, if any. Called by the
+   * payment service when an intent succeeds: finds the invoice linked by
+   * `paymentId`, marks it paid, and emits `${source}.invoice.paid` for the domain
+   * to advance on. Idempotent — no-op when no open invoice is linked (already
+   * settled, or settled inline by {@link payInvoice}).
+   */
+  async settleByPaymentId(
+    paymentId: string,
+    _providerTxnId?: string,
+    _paidAt?: Date,
+  ): Promise<Invoice | null> {
+    const invoice = await this.dataSource.getRepository(Invoice).findOne({
+      where: { paymentId, status: In(OPEN_STATUSES) },
+      order: { issuedAt: "DESC" },
+    });
+    if (!invoice) return null;
+
+    return this.markInvoiceAsPaid(invoice.id, paymentId);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
index daa3327dd..4eacedc13 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
@@ -1,6 +1,7 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 import { Freight } from '@edr/types';
+import { DataSource } from 'typeorm';
 
 import {
   BillingService,
@@ -9,7 +10,11 @@ import {
   InvoiceLineInput,
 } from '../billing/billing.service';
 import { Invoice } from '../billing/entities/invoice.entity';
+import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.service';
+import { FirstMileService } from '../first-mile/first-mile.service';
+import { BookingBatchService } from '../train-scheduling/booking-batch.service';
 import { PriceLineItemDto } from './dto/generate-price-response.dto';
+import { BookingsRepository } from './bookings.repository';
 import { Booking } from './entities/booking.entity';
 
 /** Snapshot written onto `booking.pricingBreakdown` by the pricing service. */
@@ -22,18 +27,32 @@ interface StoredPricingBreakdown {
 /** Round to 2 decimals, avoiding binary float drift. */
 const round2 = (n: number): number => Math.round(n * 100) / 100;
 
+/** Setting code holding the general-contract ordering window (months). */
+const CONTRACT_PERIOD_SETTING_CODE = 'general_contract_period';
+const DEFAULT_CONTRACT_PERIOD_MONTHS = 3;
+
 /**
  * Owns the booking ⇄ invoice mapping — the one place that knows how a booking
- * turns into invoices and which type to use. Bookings are the billable business
- * entity, so they generate their own invoices directly via {@link BillingService}
- * (billing stays source-agnostic). All booking-specific type branching lives here,
- * at the two points it belongs: invoice creation and settlement (the paid handler).
+ * turns into invoices, which type to use, and how it advances when paid. Bookings
+ * are the billable business entity, so they generate their own invoices directly
+ * via {@link BillingService} (billing stays source-agnostic). All booking-specific
+ * type branching lives here, at the two points it belongs: invoice creation and
+ * settlement (the paid handler).
  */
 @Injectable()
 export class BookingInvoiceService {
   private readonly logger = new Logger(BookingInvoiceService.name);
 
-  constructor(private readonly billing: BillingService) {}
+  constructor(
+    private readonly billing: BillingService,
+    private readonly bookingsRepository: BookingsRepository,
+    private readonly dataSource: DataSource,
+    private readonly dropdownSettings: DropdownSettingsService,
+    @Inject(forwardRef(() => FirstMileService))
+    private readonly firstMile: FirstMileService,
+    @Inject(forwardRef(() => BookingBatchService))
+    private readonly bookingBatch: BookingBatchService,
+  ) {}
 
   /**
    * Ensure the booking has its invoice, generating one from the snapshotted
@@ -71,15 +90,14 @@ export class BookingInvoiceService {
 
   /**
    * React to a booking invoice being paid — the settlement branch point. Per-type
-   * reactions live here (not in the payment process): e.g. a paid up-front invoice
-   * may later generate a final invoice. Only PREPAID exists today.
+   * reactions live here (not in the payment process): each invoice type advances
+   * the booking its own way. Only PREPAID exists today.
    */
   @OnEvent('booking.invoice.paid')
-  onBookingInvoicePaid(payload: InvoiceEventPayload): void {
+  async onBookingInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
     switch (payload.type) {
       case Freight.InvoiceType.Prepaid:
-        // Full prepaid settlement — booking advancement is handled by the
-        // payment flow today. Final-invoice issuance would hook in here.
+        await this.advanceBookingOnPayment(payload.sourceId);
         break;
       default:
         this.logger.warn(
@@ -88,6 +106,70 @@ export class BookingInvoiceService {
     }
   }
 
+  /**
+   * Advance a booking once its prepaid invoice settles. This is the domain
+   * side-effect of payment, relocated out of the payment service: a general
+   * contract becomes ACTIVE and opens its ordering window (it does not enter the
+   * train queue — nothing has been ordered yet); a normal booking becomes PAID
+   * and is allocated into its batch. Idempotent — no-op when already PAID.
+   */
+  private async advanceBookingOnPayment(bookingId: string): Promise<void> {
+    const booking = await this.bookingsRepository.findById(bookingId);
+    if (!booking) {
+      this.logger.warn(`Cannot advance unknown booking ${bookingId} on payment.`);
+      return;
+    }
+    if (booking.paymentStatus === 'PAID') return;
+
+    const paidAt = new Date();
+    const isGeneralContract = booking.bookingType === 'GENERAL_CONTRACT';
+
+    let contractExpiresAt: Date | null = null;
+    if (isGeneralContract) {
+      const months = await this.contractPeriodMonths();
+      contractExpiresAt = new Date(paidAt);
+      contractExpiresAt.setMonth(contractExpiresAt.getMonth() + months);
+    }
+
+    await this.dataSource.transaction(async (mg) => {
+      await mg.update(
+        Booking,
+        { id: bookingId },
+        isGeneralContract
+          ? { paymentStatus: 'PAID', status: 'CONTRACT_ACTIVE', expiresAt: contractExpiresAt }
+          : { paymentStatus: 'PAID', status: 'PAID' },
+      );
+      await this.firstMile.acceptBooking(bookingId);
+    });
+
+    if (isGeneralContract) {
+      this.logger.log(
+        `General contract ${booking.reference} ACTIVE — ordering open until ${contractExpiresAt?.toISOString()}`,
+      );
+      return;
+    }
+
+    try {
+      await this.bookingBatch.ensurePaidBookingAllocated(bookingId);
+    } catch (err) {
+      this.logger.error(
+        `Error allocating booking after payment: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /** Configured general-contract ordering window in months (defaults to 3). */
+  private async contractPeriodMonths(): Promise<number> {
+    try {
+      const setting = await this.dropdownSettings.getByCode(CONTRACT_PERIOD_SETTING_CODE);
+      const months = Number(setting.children?.[0]?.value);
+      if (Number.isFinite(months) && months > 0) return months;
+    } catch {
+      // Setting not seeded — fall back to the default.
+    }
+    return DEFAULT_CONTRACT_PERIOD_MONTHS;
+  }
+
   /** Map a booking's pricing snapshot into a generic invoice request. */
   private buildInput(booking: Booking): GenerateInvoiceInput | null {
     const breakdown = (booking.pricingBreakdown ?? {}) as StoredPricingBreakdown;
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-payment.controller.ts b/apps/edr-freight-api/src/modules/bookings/booking-payment.controller.ts
new file mode 100644
index 000000000..ae01ebc36
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-payment.controller.ts
@@ -0,0 +1,180 @@
+import {
+    Body,
+    Controller,
+    Get,
+    HttpStatus,
+    Post,
+    Query,
+    Res,
+} from "@nestjs/common";
+import {
+    ApiTags,
+    ApiOperation,
+    ApiQuery,
+    ApiOkResponse,
+    ApiProduces,
+} from "@nestjs/swagger";
+import { Response } from "express";
+import { Public } from "@edr/api-common";
+import { Freight } from "@edr/types";
+
+import { BillingService } from "../billing/billing.service";
+import {
+    InitiatePaymentDto,
+    InitiateResponseDto,
+    PaymentMethodTypeEnum,
+    PaymentPlatformDto,
+} from "../payment/payments.dto";
+
+/**
+ * Booking-payment entrypoints. This is the ONE place that knows a payment is for a
+ * booking — it maps the request to {@link Freight.InvoiceSource.Booking} and hands
+ * off to billing, which resolves the invoice/amount and drives the gateway. Billing
+ * and payment stay source-agnostic; the booking knowledge lives here, in the domain.
+ * Routes are unchanged (`/payments/*`) so the portal is unaffected.
+ */
+@ApiTags("Payment")
+@Controller("payments")
+export class BookingPaymentController {
+    constructor(private readonly billing: BillingService) { }
+
+    @Post("initiate")
+    @ApiOperation({
+        summary: "Initiate payment for a freight booking",
+        description: "Charges the booking's open invoice through the payment gateway.",
+    })
+    @ApiOkResponse({ type: InitiateResponseDto })
+    initiate(@Body() dto: InitiatePaymentDto): Promise<InitiateResponseDto> {
+        return this.billing.payInvoice(Freight.InvoiceSource.Booking, dto.bookingId, {
+            method: dto.method,
+            platform: dto.platform,
+            payerAccount: dto.payerAccount,
+            returnUrl: dto.returnUrl,
+            failureUrl: dto.failureUrl,
+        });
+    }
+
+    @Get("checkout")
+    @Public()
+    @ApiOperation({
+        summary: "Browser checkout redirect",
+        description:
+            "Charges the booking's invoice and returns an HTML page that auto-redirects to the provider checkout URL. Open directly in a browser tab.",
+    })
+    @ApiQuery({ name: "bookingId", required: true })
+    @ApiQuery({ name: "method", enum: PaymentMethodTypeEnum, required: true })
+    @ApiQuery({ name: "platform", enum: ["web", "mobile"], required: false })
+    @ApiProduces("text/html")
+    async checkout(
+        @Query("bookingId") bookingId: string,
+        @Query("method") method: PaymentMethodTypeEnum,
+        @Query("platform") platform: PaymentPlatformDto = "web",
+        @Res() res: Response,
+    ) {
+        if (!bookingId) {
+            return res
+                .status(HttpStatus.BAD_REQUEST)
+                .type("html")
+                .send(this.buildErrorHtml("Missing required query parameter: bookingId"));
+        }
+        if (!method || !Object.values(PaymentMethodTypeEnum).includes(method)) {
+            return res
+                .status(HttpStatus.BAD_REQUEST)
+                .type("html")
+                .send(this.buildErrorHtml("Missing or invalid query parameter: method"));
+        }
+
+        try {
+            const result = await this.billing.payInvoice(
+                Freight.InvoiceSource.Booking,
+                bookingId,
+                { method, platform },
+            );
+            const url =
+                result.clientAction?.type === "REDIRECT" ? result.clientAction.url : undefined;
+
+            if (url) {
+                return res.status(HttpStatus.OK).type("html").send(this.buildRedirectHtml(url));
+            }
+            return res
+                .status(HttpStatus.OK)
+                .type("html")
+                .send(this.buildStatusHtml(result.status, result.intentId));
+        } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : "An unexpected error occurred";
+            return res.status(HttpStatus.OK).type("html").send(this.buildErrorHtml(message));
+        }
+    }
+
+    private buildRedirectHtml(url: string): string {
+        const escaped = url.replace(/\"/g, "&quot;");
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0;url=${escaped}">
+  <title>Redirecting to payment…</title>
+  <style>
+    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
+    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
+    .spinner { width: 40px; height: 40px; border: 4px solid #e0e0e0; border-top-color: #1a73e8; border-radius: 50%; animation: spin .8s linear infinite; margin: 0 auto 20px; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    p { color: #555; margin: 0 0 16px; }
+    a { color: #1a73e8; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="spinner"></div>
+    <p>Redirecting to payment provider…</p>
+    <p><a href="${escaped}">Click here if you are not redirected</a></p>
+  </div>
+  <script>window.location.href = "${escaped}";</script>
+</body>
+</html>`;
+    }
+
+    private buildStatusHtml(status: string, intentId: string): string {
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Payment status</title>
+  <style>
+    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
+    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
+    .status { font-size: 1.1rem; font-weight: 600; color: #333; margin-bottom: 8px; }
+    small { color: #888; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="status">${status}</div>
+    <small>Intent: ${intentId}</small>
+  </div>
+</body>
+</html>`;
+    }
+
+    private buildErrorHtml(message: string): string {
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Payment error</title>
+  <style>
+    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
+    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
+    .error { color: #d32f2f; font-weight: 600; margin-bottom: 8px; }
+    p { color: #555; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="error">Payment could not be initiated</div>
+    <p>${message}</p>
+  </div>
+</body>
+</html>`;
+    }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-payment.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-payment.service.ts
index 21473eeb8..1fbe34e1f 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-payment.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-payment.service.ts
@@ -1,49 +1,37 @@
 import { Injectable, NotFoundException } from '@nestjs/common';
+import { Freight } from '@edr/types';
 import { BookingsRepository } from './bookings.repository';
 import { Booking } from './entities/booking.entity';
 import { assertBookingStatus } from './booking-status.util';
 import { InAppPaymentReceiptDto } from './dto/pay-booking.dto';
-import { PaymentService } from '../payment/payment.service';
-import { PaymentStatus } from '../payment/entities/payment.entity';
+import { BillingService } from '../billing/billing.service';
 import { PaymentMethodTypeEnum } from '../payment/payments.dto';
 export interface InAppPaymentReceipt extends InAppPaymentReceiptDto { }
 
-const NON_TERMINAL_STATUSES: PaymentStatus[] = [
-  "action-required",
-  "processing",
-  "success",
-];
-
 @Injectable()
 export class BookingPaymentService {
   constructor(
     private readonly bookingsRepository: BookingsRepository,
-    private readonly paymentService: PaymentService,
+    private readonly billing: BillingService,
   ) { }
 
+  /**
+   * Start payment for a booking. The booking never touches the payment gateway
+   * directly — it charges its invoice through billing, which resolves the amount
+   * and drives the provider. Returns the provider redirect URL (empty when none).
+   */
   async pay(bookingId: string): Promise<{ redirectUrl: string }> {
     const booking = await this.requireBooking(bookingId);
     assertBookingStatus(booking, ['FULLY_EXECUTED', 'SELECTED_FOR_BATCH', 'AWAITING_PAYMENT', '']);
 
-    const existing = await this.paymentService.findBookingById(bookingId);
-    if (existing && NON_TERMINAL_STATUSES.includes(existing.status)) {
-      if (existing.clientAction) {
-        const action = existing.clientAction as { type?: string; url?: string };
-        if (action.type === "REDIRECT" && action.url) {
-          return { redirectUrl: action.url };
-        }
-      }
-    }
-
-    const resp = await this.paymentService.initiatePayment({
-      bookingId,
+    const resp = await this.billing.payInvoice(Freight.InvoiceSource.Booking, bookingId, {
       method: PaymentMethodTypeEnum.TELEBIRR,
-      platform: "web",
+      platform: 'web',
     });
 
     const action = resp.clientAction as { type?: string; url?: string } | undefined;
     return {
-      redirectUrl: action?.type === "REDIRECT" ? (action.url ?? "") : "",
+      redirectUrl: action?.type === 'REDIRECT' ? (action.url ?? '') : '',
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 8318a4e7d..2e968309f 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -11,8 +11,11 @@ import { RuleEngineModule } from '../rule-engine/rule-engine.module';
 import { FileUploadSettingsModule } from '../file-upload-settings/file-upload-settings.module';
 import { SignaturesModule } from '../signatures/signatures.module';
 import { BillingModule } from '../billing/billing.module';
+import { DropdownSettingsModule } from '../dropdown-settings/dropdown-settings.module';
+import { FirstMileModule } from '../first-mile/first-mile.module';
 import { BookingContractService } from './booking-contract.service';
 import { BookingInvoiceService } from './booking-invoice.service';
+import { BookingPaymentController } from './booking-payment.controller';
 import { BookingPaymentService } from './booking-payment.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingReferenceDataService } from './booking-reference-data.service';
@@ -35,7 +38,6 @@ import { ContractPricingScheduleBuilder } from '../../contracts/contract-pricing
 import { ContractRendererService } from '../../contracts/contract-renderer.service';
 import { ContractTemplateResolver } from '../../contracts/contract-template.resolver';
 import { ContractViewModelBuilder } from '../../contracts/contract-view-model.builder';
-import { PaymentModule } from '../payment/payment.module';
 import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.module';
 
 @Module({
@@ -50,8 +52,9 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
       BookingReviewNote,
       BookingContractSignature,
     ]),
-    PaymentModule,
     BillingModule,
+    DropdownSettingsModule,
+    forwardRef(() => FirstMileModule),
     forwardRef(() => TrainSchedulingModule),
     FilesModule,
     MinioModule,
@@ -66,7 +69,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
         config.get<ExchangeOptions>('app.cbeExchange') ?? {},
     }),
   ],
-  controllers: [BookingsController, PayController],
+  controllers: [BookingsController, PayController, BookingPaymentController],
   providers: [
     BookingsService,
     BookingsRepository,
diff --git a/apps/edr-freight-api/src/modules/payment/payment.controller.ts b/apps/edr-freight-api/src/modules/payment/payment.controller.ts
index f1f34c3b1..b1b269665 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.controller.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.controller.ts
@@ -1,13 +1,13 @@
 import {
-    Body,
     Controller,
     Get,
     HttpStatus,
     Param,
     ParseUUIDPipe,
-    Post,
     Query,
     Res,
+    Body,
+    Post,
 } from "@nestjs/common";
 import {
     ApiTags,
@@ -20,14 +20,7 @@ import { Response } from "express";
 import { Public } from "@edr/api-common";
 import { BookingView, FreightAdmin } from "../../common/booking-guards";
 import { PaymentService } from "./payment.service";
-import {
-    InitiatePaymentDto,
-    InitiateResponseDto,
-    IntentStatusDto,
-    PaymentMethodTypeEnum,
-    PaymentPlatformDto,
-    RefundDto,
-} from "./payments.dto";
+import { IntentStatusDto, RefundDto } from "./payments.dto";
 
 @ApiTags("Payment")
 @Controller("payments")
@@ -73,16 +66,6 @@ export class PaymentController {
         });
     }
 
-    @Post("initiate")
-    @ApiOperation({
-        summary: "Initiate payment for a freight booking",
-        description: `Initiates payment via the central payment microservice.\n\n**Supported methods:**\n- TELEBIRR — Ethiopian mobile money\n- CBE_BIRR — Commercial Bank of Ethiopia\n- EBIRR — Electronic payment gateway\n- WAAFI — Djibouti mobile money\n- CARD — Visa/Mastercard\n- DMONEY — Djibouti D-money\n- CAC_BANK — CAC Int Bank (OTP)`,
-    })
-    @ApiOkResponse({ type: InitiateResponseDto })
-    initiatePayment(@Body() dto: InitiatePaymentDto) {
-        return this.paymentService.initiatePayment(dto);
-    }
-
     @Get("intents/:bookingId")
     @ApiOperation({ summary: "Get payment intent status for a booking" })
     @ApiOkResponse({ type: IntentStatusDto })
@@ -97,54 +80,6 @@ export class PaymentController {
         return this.paymentService.refund(dto);
     }
 
-    @Get("checkout")
-    @Public()
-    @ApiOperation({
-        summary: "Browser checkout redirect",
-        description:
-            "Initiates payment and returns an HTML page that auto-redirects to the provider checkout URL. Open directly in a browser tab.",
-    })
-    @ApiQuery({ name: "bookingId", required: true })
-    @ApiQuery({ name: "method", enum: PaymentMethodTypeEnum, required: true })
-    @ApiQuery({ name: "platform", enum: ["web", "mobile"], required: false })
-    @ApiProduces("text/html")
-    async checkout(
-        @Query("bookingId") bookingId: string,
-        @Query("method") method: PaymentMethodTypeEnum,
-        @Query("platform") platform: PaymentPlatformDto = "web",
-        @Res() res: Response,
-    ) {
-        if (!bookingId) {
-            return res
-                .status(HttpStatus.BAD_REQUEST)
-                .type("html")
-                .send(this.buildErrorHtml("Missing required query parameter: bookingId"));
-        }
-        if (!method || !Object.values(PaymentMethodTypeEnum).includes(method)) {
-            return res
-                .status(HttpStatus.BAD_REQUEST)
-                .type("html")
-                .send(this.buildErrorHtml("Missing or invalid query parameter: method"));
-        }
-
-        try {
-            const result = await this.paymentService.initiatePayment({ bookingId, method, platform });
-            const url =
-                result.clientAction?.type === "REDIRECT" ? result.clientAction.url : undefined;
-
-            if (url) {
-                return res.status(HttpStatus.OK).type("html").send(this.buildRedirectHtml(url));
-            }
-            return res
-                .status(HttpStatus.OK)
-                .type("html")
-                .send(this.buildStatusHtml(result.status, result.intentId));
-        } catch (err: unknown) {
-            const message = err instanceof Error ? err.message : "An unexpected error occurred";
-            return res.status(HttpStatus.OK).type("html").send(this.buildErrorHtml(message));
-        }
-    }
-
     @Get("receipt/:orderId")
     @Public()
     @ApiOperation({ summary: "Generate a payment receipt HTML page" })
@@ -153,76 +88,4 @@ export class PaymentController {
         const html = await this.paymentService.genReceiptHtml(orderId);
         return res.status(HttpStatus.OK).type("html").send(html);
     }
-
-    private buildRedirectHtml(url: string): string {
-        const escaped = url.replace(/\"/g, "&quot;");
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta http-equiv="refresh" content="0;url=${escaped}">
-  <title>Redirecting to payment…</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .spinner { width: 40px; height: 40px; border: 4px solid #e0e0e0; border-top-color: #1a73e8; border-radius: 50%; animation: spin .8s linear infinite; margin: 0 auto 20px; }
-    @keyframes spin { to { transform: rotate(360deg); } }
-    p { color: #555; margin: 0 0 16px; }
-    a { color: #1a73e8; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="spinner"></div>
-    <p>Redirecting to payment provider…</p>
-    <p><a href="${escaped}">Click here if you are not redirected</a></p>
-  </div>
-  <script>window.location.href = "${escaped}";</script>
-</body>
-</html>`;
-    }
-
-    private buildStatusHtml(status: string, intentId: string): string {
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Payment status</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .status { font-size: 1.1rem; font-weight: 600; color: #333; margin-bottom: 8px; }
-    small { color: #888; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="status">${status}</div>
-    <small>Intent: ${intentId}</small>
-  </div>
-</body>
-</html>`;
-    }
-
-    private buildErrorHtml(message: string): string {
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Payment error</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .error { color: #d32f2f; font-weight: 600; margin-bottom: 8px; }
-    p { color: #555; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="error">Payment could not be initiated</div>
-    <p>${message}</p>
-  </div>
-</body>
-</html>`;
-    }
 }
diff --git a/apps/edr-freight-api/src/modules/payment/payment.module.ts b/apps/edr-freight-api/src/modules/payment/payment.module.ts
index 18e32330d..330521218 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.module.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.module.ts
@@ -1,4 +1,4 @@
-import { DynamicModule, Module, forwardRef } from "@nestjs/common";
+import { DynamicModule, forwardRef, Module } from "@nestjs/common";
 import { HttpModule } from "@nestjs/axios";
 import { ConfigModule, ConfigService } from "@nestjs/config";
 import { RabbitMQModule } from "@golevelup/nestjs-rabbitmq";
@@ -13,9 +13,6 @@ import {
 
 import { ServiceAuthGuard } from "../../common/guards/service-auth.guard";
 import { BillingModule } from "../billing/billing.module";
-import { DropdownSettingsModule } from "../dropdown-settings/dropdown-settings.module";
-import { FirstMileModule } from "../first-mile/first-mile.module";
-import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.module";
 import { PaymentRefundEntity } from "./entities/payment-refund.entity";
 import { PaymentWebhookEventEntity } from "./entities/payment-webhook-event.entity";
 import { PaymentEntity } from "./entities/payment.entity";
@@ -59,10 +56,7 @@ function rabbitMQImport(): DynamicModule[] {
     imports: [
         HttpModule.register({ timeout: 10_000 }),
         ConfigModule,
-        DropdownSettingsModule,
-        BillingModule,
-        forwardRef(() => FirstMileModule),
-        forwardRef(() => TrainSchedulingModule),
+        forwardRef(() => BillingModule),
         TypeOrmModule.forFeature([
             PaymentEntity,
             PaymentWebhookEventEntity,
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 5fb77f404..7beb6e8c6 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -11,6 +11,7 @@ import { DataSource } from "typeorm";
 import { PaymentEntity } from "./entities/payment.entity";
 import { PaymentRepository } from "./payment.repository";
 import { PaymentClientService } from "./payment-client.service";
+import { BillingService } from "../billing/billing.service";
 
 import * as fs from "fs";
 import * as path from "path";
@@ -22,26 +23,46 @@ import {
     ProviderPaymentStatus,
 } from "@edr/payment-providers";
 import {
-    Freight,
     PaymentService as PaymentServiceEnum,
     PaymentReferenceType,
     PaymentIntentSnapshot,
     ProviderMethod,
 } from "@edr/types";
-import { BillingService } from "../billing/billing.service";
 import {
-    InitiatePaymentDto,
     InitiateResponseDto,
     IntentStatusDto,
+    PaymentPlatformDto,
     RefundDto,
 } from "./payments.dto";
-import { BookingBatchService } from "../train-scheduling/booking-batch.service";
-import { DropdownSettingsService } from "../dropdown-settings/dropdown-settings.service";
-import { FirstMileService } from "../first-mile/first-mile.service";
 
-/** Setting code holding the global ordering window (months) for general contracts. */
-const CONTRACT_PERIOD_SETTING_CODE = "general_contract_period";
-const DEFAULT_CONTRACT_PERIOD_MONTHS = 3;
+/** Everything the gateway needs to open an intent. Amount/currency are supplied by
+ *  the caller (billing) — this service never derives them from a domain record. */
+export interface InitiateIntentInput {
+    /** Opaque domain reference (booking id, …). */
+    referenceId: string;
+    /** Human-readable order ref shown on provider pages. */
+    orderRef: string;
+    /** Authoritative amount in minor units, computed by the caller. */
+    amountMinor: number;
+    currency: string;
+    /** Stored on the intent projection for receipts/dashboards. */
+    reason?: string;
+    /** Provider/method selector. */
+    method: ProviderMethod | string;
+    platform?: PaymentPlatformDto;
+    payerAccount?: string;
+    returnUrl?: string;
+    failureUrl?: string;
+}
+
+export interface InitiateIntentResult {
+    intentId: string;
+    response: InitiateResponseDto;
+    /** True when the provider settled the charge synchronously during initiate. */
+    immediateSuccess: boolean;
+    providerTxnId?: string;
+    paidAt?: Date;
+}
 
 const STATUS_MAP: Record<string, ProviderPaymentStatus> = {
     "action-required": ProviderPaymentStatus.REQUIRES_ACTION,
@@ -52,6 +73,23 @@ const STATUS_MAP: Record<string, ProviderPaymentStatus> = {
     "refunded": ProviderPaymentStatus.CANCELLED,
 };
 
+const PROVIDER_TO_METHOD: Record<string, PaymentEntity["method"]> = {
+    TELEBIRR: "telebirr",
+    CBE_BIRR: "cbe-birr",
+    EBIRR: "ebirr",
+    WAAFI: "waafi",
+    CARD: "card",
+    DMONEY: "dmoney",
+    CAC_BANK: "cac-bank",
+};
+
+/**
+ * Pure payment-gateway adapter. Owns intents, provider calls and webhooks — and
+ * NOTHING domain-specific: it never loads a booking, computes an amount, or
+ * advances a domain record. On settlement it notifies billing directly
+ * ({@link BillingService.settleByPaymentId}); billing (and through it, the domain)
+ * reacts. The billing↔payment pair is a deliberate forwardRef cycle.
+ */
 @Injectable()
 export class PaymentService {
     private readonly logger = new Logger(PaymentService.name);
@@ -60,27 +98,10 @@ export class PaymentService {
         private readonly datasource: DataSource,
         private readonly paymentRepo: PaymentRepository,
         private readonly paymentClient: PaymentClientService,
-        @Inject(forwardRef(() => BookingBatchService))
-        private readonly bookingBatchService: BookingBatchService,
-        private readonly dropdownSettings: DropdownSettingsService,
-        private readonly firstMileService: FirstMileService,
+        @Inject(forwardRef(() => BillingService))
         private readonly billing: BillingService,
     ) { }
 
-    /** Configured general-contract ordering window in months (defaults to 3). */
-    private async contractPeriodMonths(): Promise<number> {
-        try {
-            const setting = await this.dropdownSettings.getByCode(
-                CONTRACT_PERIOD_SETTING_CODE,
-            );
-            const months = Number(setting.children?.[0]?.value);
-            if (Number.isFinite(months) && months > 0) return months;
-        } catch {
-            // Setting not seeded — fall back to the default.
-        }
-        return DEFAULT_CONTRACT_PERIOD_MONTHS;
-    }
-
     async getAll(filters: {
         search?: string;
         status?: string;
@@ -146,7 +167,6 @@ export class PaymentService {
             total += row.count;
         }
 
-        // Sum of successfully collected amounts.
         const paidAgg = await this.paymentRepo
             .createQueryBuilder("payment")
             .select("COALESCE(SUM(payment.amount), 0)", "sum")
@@ -164,74 +184,75 @@ export class PaymentService {
         };
     }
 
-    async initiatePayment(dto: InitiatePaymentDto): Promise<InitiateResponseDto> {
-        const booking = await this.datasource
-            .getRepository(Booking)
-            .findOneBy({ id: dto.bookingId });
-        if (!booking) throw new NotFoundException("Booking not found");
-
-        // Charge the invoice (the billing document of record) so discounts,
-        // penalties and staff adjustments carried on it are honored. Fall back to
-        // the booking total only when no invoice has been generated yet.
-        const invoice = await this.billing.findPayable(
-            Freight.InvoiceSource.Booking,
-            booking.id,
-        );
-        const amountMinor = Math.round(
-            Number(invoice?.totalAmount ?? booking.totalAmount),
-        );
-
+    /**
+     * Open a gateway intent for a caller-supplied amount/reference and project it
+     * locally. Returns the intent id (so billing can correlate the invoice) plus
+     * the client action. When the provider settles synchronously, the intent is
+     * marked paid WITHOUT emitting — the caller (billing) settles inline after it
+     * has stored the intent id, avoiding a settle-before-correlation race.
+     */
+    async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
         const snapshot = await this.paymentClient.initiate({
             service: PaymentServiceEnum.FREIGHT,
             referenceType: PaymentReferenceType.SHIPMENT,
-            referenceId: booking.id,
-            orderRef: booking.reference,
-            amountMinor,
-            currency: booking.paymentCurrency,
-            provider: dto.method as unknown as ProviderMethod,
-            platform: dto.platform,
-            payerAccount: dto.payerAccount,
-            returnUrl:'https://edrfreight.triaplc.com/payment/success',
-            failureUrl: 'https://edrfreight.triaplc.com/payment/failure',
+            referenceId: input.referenceId,
+            orderRef: input.orderRef,
+            amountMinor: input.amountMinor,
+            currency: input.currency,
+            provider: input.method as ProviderMethod,
+            platform: input.platform,
+            payerAccount: input.payerAccount,
+            returnUrl: input.returnUrl ?? "https://edrfreight.triaplc.com/payment/success",
+            failureUrl: input.failureUrl ?? "https://edrfreight.triaplc.com/payment/failure",
         });
 
-        const intent = await this.syncIntentProjection(booking.id, booking, snapshot);
+        const immediateSuccess = snapshot.status === ProviderPaymentStatus.SUCCEEDED;
+        const paidAt = snapshot.paidAt ? new Date(snapshot.paidAt) : undefined;
 
-        if (snapshot.status === ProviderPaymentStatus.SUCCEEDED) {
-            await this.finalizePaymentSuccess({
-                intentId: intent.id,
-                bookingId: booking.id,
+        const intent = await this.upsertIntent(input, snapshot);
+
+        if (immediateSuccess) {
+            // Settle the projection but DO NOT notify billing — billing settles
+            // inline once it has stored intentId on the invoice (see payInvoice),
+            // avoiding a settle-before-correlation race.
+            await this.markIntentSucceeded(intent.id, {
                 providerTxnId: snapshot.providerTxnId,
-                paidAt: snapshot.paidAt ? new Date(snapshot.paidAt) : undefined,
+                paidAt,
+                notify: false,
             });
         }
 
-        return this.formatIntentResponse(intent);
+        return {
+            intentId: intent.id,
+            // `intent` still reflects the projection status ("processing" on immediate
+            // success — settlement is applied by the caller, not shown synchronously).
+            response: this.formatIntentResponse(intent),
+            immediateSuccess,
+            providerTxnId: snapshot.providerTxnId,
+            paidAt,
+        };
     }
 
-    private async syncIntentProjection(
-        bookingId: string,
-        booking: Booking,
+    /** Create or update the local intent projection from a provider snapshot. */
+    private async upsertIntent(
+        input: InitiateIntentInput,
         snapshot: PaymentIntentSnapshot,
     ): Promise<PaymentEntity> {
-        const existing = await this.paymentRepo.findOneBy({ refId: bookingId, type: "booking" });
+        const existing = await this.paymentRepo.findOneBy({
+            refId: input.referenceId,
+            type: "booking",
+        });
 
-        const PROVIDER_TO_METHOD: Record<string, PaymentEntity["method"]> = {
-            TELEBIRR: "telebirr",
-            CBE_BIRR: "cbe-birr",
-            EBIRR: "ebirr",
-            WAAFI: "waafi",
-            CARD: "card",
-            DMONEY: "dmoney",
-            CAC_BANK: "cac-bank",
-        };
         const method: PaymentEntity["method"] =
             PROVIDER_TO_METHOD[snapshot.provider ?? ""] ?? "telebirr";
-        const status = snapshot.status === ProviderPaymentStatus.SUCCEEDED
-            ? "processing"
-            : this.toLocalStatus(snapshot.status);
+        const status =
+            snapshot.status === ProviderPaymentStatus.SUCCEEDED
+                ? "processing"
+                : this.toLocalStatus(snapshot.status);
 
-        const clientAction = (snapshot.clientAction ?? undefined) as Record<string, unknown> | undefined;
+        const clientAction = (snapshot.clientAction ?? undefined) as
+            | Record<string, unknown>
+            | undefined;
         const data = {
             status,
             method,
@@ -248,30 +269,36 @@ export class PaymentService {
         }
 
         return this.paymentRepo.create({
-            refId: bookingId,
+            refId: input.referenceId,
             type: "booking",
-            amount: booking.totalAmount,
-            currency: booking.paymentCurrency,
-            reason: `Payment for booking ${booking.reference}`,
+            amount: input.amountMinor,
+            currency: input.currency as PaymentEntity["currency"],
+            reason: input.reason ?? `Payment for ${input.orderRef}`,
             rawInitiation: snapshot as unknown as Record<string, unknown>,
             clientAction: clientAction ?? {},
             ...data,
         } as any);
     }
 
-    async getIntentByBookingId(bookingId: string): Promise<IntentStatusDto> {
-        const local = await this.paymentRepo.findOneBy({ refId: bookingId, type: "booking" });
+    /**
+     * Reconcile an intent's status with the gateway by reference. Read-only on the
+     * domain side: it syncs the local projection and, when the provider reports a
+     * newly-observed success, notifies billing to settle. `referenceId` is opaque
+     * (the booking id, but this service does not load it).
+     */
+    async getIntentByBookingId(referenceId: string): Promise<IntentStatusDto> {
+        const local = await this.paymentRepo.findOneBy({ refId: referenceId, type: "booking" });
 
         let snapshot: PaymentIntentSnapshot | null = null;
         try {
             snapshot = await this.paymentClient.getIntentByReference(
                 PaymentReferenceType.SHIPMENT,
-                bookingId,
+                referenceId,
             );
         } catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             this.logger.warn(
-                `payment service lookup failed for booking ${bookingId}: ${message}; using local intent`,
+                `payment service lookup failed for reference ${referenceId}: ${message}; using local intent`,
             );
         }
 
@@ -279,111 +306,54 @@ export class PaymentService {
             if (!local) throw new NotFoundException("PaymentIntent not found");
             return this.formatIntentStatus(local);
         }
+        if (!local) throw new NotFoundException("PaymentIntent not found");
 
-        const booking = await this.datasource
-            .getRepository(Booking)
-            .findOneBy({ id: bookingId });
+        // Sync local projection with provider-reported status.
+        const becameSuccess =
+            snapshot.status === ProviderPaymentStatus.SUCCEEDED && local.status !== "success";
 
-        if (!booking) throw new NotFoundException("Booking not found");
-
-        const intent = await this.syncIntentProjection(bookingId, booking, snapshot);
-
-        if (snapshot.status === ProviderPaymentStatus.SUCCEEDED) {
-            await this.finalizePaymentSuccess({
-                intentId: intent.id,
-                bookingId: booking.id,
+        if (becameSuccess) {
+            await this.markIntentSucceeded(local.id, {
                 providerTxnId: snapshot.providerTxnId,
                 paidAt: snapshot.paidAt ? new Date(snapshot.paidAt) : undefined,
+                notify: true,
             });
+        } else if (snapshot.status !== ProviderPaymentStatus.SUCCEEDED) {
+            await this.paymentRepo.update(
+                { id: local.id },
+                {
+                    status: this.toLocalStatus(snapshot.status),
+                    failerCode: snapshot.failureCode ?? undefined,
+                    failureMessage: snapshot.failureMessage ?? undefined,
+                },
+            );
         }
 
-        const refreshed = await this.paymentRepo.findOneBy({ id: intent.id });
-        return this.formatIntentStatus(refreshed ?? intent);
+        const refreshed = await this.paymentRepo.findOneBy({ id: local.id });
+        return this.formatIntentStatus(refreshed ?? local);
     }
 
-    async refund(dto: RefundDto) {
-        const intent = await this.paymentRepo.findOneBy({ refId: dto.bookingId, type: "booking" });
-        if (!intent || intent.status !== "success") {
-            throw new BadRequestException("No successful payment to refund");
-        }
-
-        await this.datasource.transaction(async (mg) => {
-            await mg.update(PaymentEntity, { id: intent.id }, { status: "refunded", refundedAt: new Date() });
-            await mg.update(Booking, { id: dto.bookingId }, { paymentStatus: "FAILED", status: "CANCELLED" });
-        });
-
-        return { refunded: true, bookingId: dto.bookingId };
-    }
-
-    async finalizePaymentSuccess(input: {
-        intentId: string;
-        bookingId: string;
-        providerTxnId?: string;
-        paidAt?: Date;
-    }): Promise<{ alreadyFinalized: boolean }> {
-        const intent = await this.paymentRepo.findOneBy({ id: input.intentId });
+    /**
+     * Mark a gateway intent paid and (by default) notify billing to settle the
+     * linked invoice. Idempotent — no-op when already success. Pass `notify: false`
+     * when the caller settles inline and will trigger settlement itself.
+     */
+    async markIntentSucceeded(
+        intentId: string,
+        opts: { providerTxnId?: string; paidAt?: Date; notify?: boolean } = {},
+    ): Promise<{ alreadyFinalized: boolean }> {
+        const intent = await this.paymentRepo.findOneBy({ id: intentId });
         if (!intent) throw new NotFoundException("PaymentIntent not found");
         if (intent.status === "success") return { alreadyFinalized: true };
 
-        const paidAt = input.paidAt ?? new Date();
+        const paidAt = opts.paidAt ?? new Date();
+        await this.paymentRepo.update(
+            { id: intent.id },
+            { status: "success", paidAt, transactionId: opts.providerTxnId ?? intent.transactionId },
+        );
 
-        // A general contract is paid once, up front; it does NOT enter the train
-        // queue (nothing has been ordered yet). Instead it becomes ACTIVE and
-        // opens its ordering window. Orders placed later spawn their own paid
-        // child bookings that go through the normal pipeline.
-        const booking = await this.datasource
-            .getRepository(Booking)
-            .findOne({ where: { id: input.bookingId } });
-        const isGeneralContract = booking?.bookingType === "GENERAL_CONTRACT";
-
-        let contractExpiresAt: Date | null = null;
-        if (isGeneralContract) {
-            const months = await this.contractPeriodMonths();
-            contractExpiresAt = new Date(paidAt);
-            contractExpiresAt.setMonth(contractExpiresAt.getMonth() + months);
-        }
-
-        await this.datasource.transaction(async (mg) => {
-            await mg.update(
-                PaymentEntity,
-                { id: intent.id },
-                { status: "success", paidAt, transactionId: input.providerTxnId ?? intent.transactionId },
-            );
-            await mg.update(
-                Booking,
-                { id: input.bookingId },
-                isGeneralContract
-                    ? { paymentStatus: "PAID", status: "CONTRACT_ACTIVE", expiresAt: contractExpiresAt }
-                    : { paymentStatus: "PAID", status: "PAID" },
-            );
-
-            // Settle the booking's open invoice in the same transaction and link
-            // this payment. The invoice emits `booking.invoice.paid` for the source
-            // to react to. No-op if the booking has no open invoice.
-            await this.billing.settlePayable(
-                Freight.InvoiceSource.Booking,
-                input.bookingId,
-                intent.id,
-                mg,
-            );
-
-                        await this.firstMileService.acceptBooking(input.bookingId);
-
-        });
-
-        if (isGeneralContract) {
-            this.logger.log(
-                `General contract ${booking?.reference ?? input.bookingId} ACTIVE — ordering open until ${contractExpiresAt?.toISOString()}`,
-            );
-            return { alreadyFinalized: false };
-        }
-
-        try {
-            await this.bookingBatchService.ensurePaidBookingAllocated(input.bookingId);
-        } catch (err) {
-            this.logger.error(
-                `Error allocating booking after payment: ${err instanceof Error ? err.message : String(err)}`,
-            );
+        if (opts.notify !== false) {
+            await this.billing.settleByPaymentId(intent.id, opts.providerTxnId, paidAt);
         }
 
         return { alreadyFinalized: false };
@@ -402,6 +372,29 @@ export class PaymentService {
             { id: intent.id },
             { status: "failed", failerCode: input.failureCode, failureMessage: input.failureMessage },
         );
+
+        // Invoice stays open for retry — nothing to settle. Logged only.
+        this.logger.warn(
+            `Payment ${intent.id} failed for ${intent.refId}` +
+            (input.failureMessage ? `: ${input.failureMessage}` : ""),
+        );
+    }
+
+    async refund(dto: RefundDto) {
+        const intent = await this.paymentRepo.findOneBy({ refId: dto.bookingId, type: "booking" });
+        if (!intent || intent.status !== "success") {
+            throw new BadRequestException("No successful payment to refund");
+        }
+
+        // NOTE: refunding still mutates the booking directly — left intact pending
+        // the refund redesign. TODO: route refunds through billing.refundPayable +
+        // a `${source}.invoice.refunded` reaction, like settlement.
+        await this.datasource.transaction(async (mg) => {
+            await mg.update(PaymentEntity, { id: intent.id }, { status: "refunded", refundedAt: new Date() });
+            await mg.update(Booking, { id: dto.bookingId }, { paymentStatus: "FAILED", status: "CANCELLED" });
+        });
+
+        return { refunded: true, bookingId: dto.bookingId };
     }
 
     async getActivePaymentByOrderIdAndMethod(orderId: string, method: PaymentEntity["method"]): Promise<PaymentEntity | null> {
@@ -468,13 +461,12 @@ export class PaymentService {
         if (event.eventType === "payment.succeeded") {
             const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId, type: "booking" });
             if (!intent) {
-                return { processed: false, reason: `No local intent for booking ${event.referenceId}` };
+                return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
             }
-            const { alreadyFinalized } = await this.finalizePaymentSuccess({
-                intentId: intent.id,
-                bookingId: event.referenceId,
+            const { alreadyFinalized } = await this.markIntentSucceeded(intent.id, {
                 providerTxnId: event.providerTxnId,
                 paidAt: event.paidAt ? new Date(event.paidAt) : undefined,
+                notify: true,
             });
             return { processed: true, alreadyFinalized };
         }
@@ -482,7 +474,7 @@ export class PaymentService {
         if (event.eventType === "payment.failed") {
             const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId, type: "booking" });
             if (!intent) {
-                return { processed: false, reason: `No local intent for booking ${event.referenceId}` };
+                return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
             }
             await this.markPaymentFailed({
                 intentId: intent.id,
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 374eee28a..6375a0369 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -140,11 +140,18 @@ export enum InvoiceStatus {
 /** Originating subsystem an invoice bills for; namespaces invoice events. */
 export enum InvoiceSource {
   Booking = "booking",
-  Contract = "contract",
   Warehouse = "warehouse",
   Demurrage = "demurrage",
 }
 
+/**
+ * What an invoice bills for within its source — the discriminator when one
+ * entity carries several invoices (e.g. a booking's up-front vs final charge).
+ */
+export enum InvoiceType {
+  Prepaid = "PREPAID",
+}
+
 export enum SchedulingStatus {
   NotScheduled = "NOT_SCHEDULED",
   Holding = "HOLDING",

From 2551f76f8a9f7b6a339b4e5f99f6f5dfeaef792b Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 09:50:29 +0000
Subject: [PATCH 12/63] fix: reference type in payment and billing

---
 .../1821000000004-MakePaymentsTypeGeneric.ts  | 47 +++++++++++++++++++
 .../src/modules/billing/billing.service.ts    |  8 +++-
 .../payment/entities/payment.entity.ts        |  8 +++-
 .../src/modules/payment/payment.service.ts    | 20 ++++----
 4 files changed, 72 insertions(+), 11 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts

diff --git a/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts b/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts
new file mode 100644
index 000000000..9f0e8e7bd
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts
@@ -0,0 +1,47 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Make the payment projection source-agnostic so any domain (not just bookings)
+ * can own a payment intent.
+ *
+ *   - `payments.type` enum `('booking')` → `varchar(50)`. It now stores the
+ *     invoice SOURCE (e.g. 'booking', 'demurrage'), supplied by the caller, so a
+ *     new domain no longer needs an enum migration to write its intents.
+ *   - adds `payments.reference_type varchar(40)` — the gateway reference type
+ *     (`PaymentReferenceType`) the intent was opened with, so the reconcile/poll
+ *     path can query the provider without hardcoding it.
+ *
+ * Matches payment/entities/payment.entity.ts.
+ */
+export class MakePaymentsTypeGeneric1821000000004 implements MigrationInterface {
+  name = "MakePaymentsTypeGeneric1821000000004";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.payments ALTER COLUMN type TYPE varchar(50) USING type::text;`,
+    );
+    await queryRunner.query(`DROP TYPE IF EXISTS freight.payments_type_enum;`);
+
+    await queryRunner.query(
+      `ALTER TABLE freight.payments ADD COLUMN reference_type varchar(40);`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.payments DROP COLUMN IF EXISTS reference_type;`,
+    );
+
+    // Restore the single-value enum. Any non-'booking' rows would block the cast;
+    // collapse them first so the down migration is safe.
+    await queryRunner.query(
+      `UPDATE freight.payments SET type = 'booking' WHERE type <> 'booking';`,
+    );
+    await queryRunner.query(
+      `CREATE TYPE freight.payments_type_enum AS ENUM ('booking');`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.payments ALTER COLUMN type TYPE freight.payments_type_enum USING type::freight.payments_type_enum;`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 448ad6685..1d0473c7e 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,6 +1,6 @@
 import { forwardRef, Inject, Injectable, Logger, NotFoundException } from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
-import { Freight } from "@edr/types";
+import { Freight, PaymentReferenceType } from "@edr/types";
 import { DataSource, EntityManager, In } from "typeorm";
 
 import { Invoice } from "./entities/invoice.entity";
@@ -417,6 +417,12 @@ export class BillingService {
 
     const result = await this.payment.initiate({
       referenceId: sourceId,
+      source: invoice.source,
+      // Gateway reference type derives from the invoice source by convention
+      // (source.toUpperCase() ∈ PaymentReferenceType) — no domain word here, and
+      // the domain never supplies it. New sources add their uppercased value to
+      // the PaymentReferenceType enum.
+      referenceType: invoice.source.toUpperCase() as PaymentReferenceType,
       orderRef: invoice.invoiceNumber,
       amountMinor: Math.round(Number(invoice.totalAmount)),
       currency: invoice.currency,
diff --git a/apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts b/apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts
index 2bb81a331..5c4a4f7f7 100644
--- a/apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts
+++ b/apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts
@@ -2,7 +2,8 @@ import { BaseEntity, Column, CreateDateColumn, Entity, OneToMany, PrimaryGenerat
 import { PaymentRefundEntity } from "./payment-refund.entity";
 
 
-type PaymentType = "booking"
+/** Invoice source that owns the intent ('booking', 'demurrage', …) — caller-supplied. */
+type PaymentType = string
 type PaymentMethod = "telebirr" | "cbe-birr" | "ebirr" | "waafi" | "card" | "dmoney" | "cac-bank"
 type Currency = "ETB" | "USD"
 export type PaymentStatus = "action-required" | "processing" | "success" | "failed" | "canceled" | "refunded"
@@ -15,9 +16,12 @@ export class PaymentEntity extends BaseEntity {
     @Column({ type: 'varchar', length: 255, name: "ref_id" })
     refId!: string
 
-    @Column({ type: "enum", enum: ["booking"] })
+    @Column({ type: "varchar", length: 50 })
     type!: PaymentType;
 
+    @Column({ type: "varchar", length: 40, nullable: true, name: "reference_type" })
+    referenceType?: string;
+
     @Column({ type: "enum", enum: ["telebirr", "cbe-birr", "ebirr", "waafi", "card", "dmoney", "cac-bank"] })
     method!: PaymentMethod
 
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 7beb6e8c6..a712e4ad8 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -40,6 +40,10 @@ import {
 export interface InitiateIntentInput {
     /** Opaque domain reference (booking id, …). */
     referenceId: string;
+    /** Invoice source that owns the intent ('booking', …) — stored on the projection. */
+    source: string;
+    /** Gateway reference type the intent is opened with (caller's domain decides it). */
+    referenceType: PaymentReferenceType;
     /** Human-readable order ref shown on provider pages. */
     orderRef: string;
     /** Authoritative amount in minor units, computed by the caller. */
@@ -194,7 +198,7 @@ export class PaymentService {
     async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
         const snapshot = await this.paymentClient.initiate({
             service: PaymentServiceEnum.FREIGHT,
-            referenceType: PaymentReferenceType.SHIPMENT,
+            referenceType: input.referenceType,
             referenceId: input.referenceId,
             orderRef: input.orderRef,
             amountMinor: input.amountMinor,
@@ -240,7 +244,6 @@ export class PaymentService {
     ): Promise<PaymentEntity> {
         const existing = await this.paymentRepo.findOneBy({
             refId: input.referenceId,
-            type: "booking",
         });
 
         const method: PaymentEntity["method"] =
@@ -270,7 +273,8 @@ export class PaymentService {
 
         return this.paymentRepo.create({
             refId: input.referenceId,
-            type: "booking",
+            type: input.source,
+            referenceType: input.referenceType,
             amount: input.amountMinor,
             currency: input.currency as PaymentEntity["currency"],
             reason: input.reason ?? `Payment for ${input.orderRef}`,
@@ -287,12 +291,12 @@ export class PaymentService {
      * (the booking id, but this service does not load it).
      */
     async getIntentByBookingId(referenceId: string): Promise<IntentStatusDto> {
-        const local = await this.paymentRepo.findOneBy({ refId: referenceId, type: "booking" });
+        const local = await this.paymentRepo.findOneBy({ refId: referenceId });
 
         let snapshot: PaymentIntentSnapshot | null = null;
         try {
             snapshot = await this.paymentClient.getIntentByReference(
-                PaymentReferenceType.SHIPMENT,
+                (local?.referenceType as PaymentReferenceType) ?? PaymentReferenceType.SHIPMENT,
                 referenceId,
             );
         } catch (err) {
@@ -423,7 +427,7 @@ export class PaymentService {
     }
 
     findBookingById(id: string) {
-        return this.paymentRepo.findOneBy({ refId: id, type: "booking" });
+        return this.paymentRepo.findOneBy({ refId: id });
     }
 
     formatIntentResponse(intent: PaymentEntity): InitiateResponseDto {
@@ -459,7 +463,7 @@ export class PaymentService {
         failureMessage?: string;
     }): Promise<{ processed: boolean; alreadyFinalized?: boolean; reason?: string }> {
         if (event.eventType === "payment.succeeded") {
-            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId, type: "booking" });
+            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId });
             if (!intent) {
                 return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
             }
@@ -472,7 +476,7 @@ export class PaymentService {
         }
 
         if (event.eventType === "payment.failed") {
-            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId, type: "booking" });
+            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId });
             if (!intent) {
                 return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
             }

From 662d96571eafa798306165ecfebfde1c3c96ab4a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 11:14:42 +0000
Subject: [PATCH 13/63] fix

---
 .../booking-orders/booking-orders.service.ts  | 470 ------------------
 .../bookings/booking-invoice.service.ts       |   5 +-
 2 files changed, 3 insertions(+), 472 deletions(-)
 delete mode 100644 apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts

diff --git a/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts b/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts
deleted file mode 100644
index 210b65b3d..000000000
--- a/apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts
+++ /dev/null
@@ -1,470 +0,0 @@
-import {
-  BadRequestException,
-  forwardRef,
-  Inject,
-  Injectable,
-  Logger,
-  NotFoundException,
-} from '@nestjs/common';
-import { DataSource } from 'typeorm';
-import { BookingsRepository } from '../bookings/bookings.repository';
-import { BookingPricingService } from '../bookings/booking-pricing.service';
-import { clearanceCodesForBooking } from '../bookings/clearance.util';
-import { Booking } from '../bookings/entities/booking.entity';
-import { BookingContainer } from '../bookings/entities/booking-container.entity';
-import { CompaniesService } from '../companies/companies.service';
-import { ContainerType } from '../rule-engine/entities/container-type.entity';
-import { RatesService } from '../rule-engine/services/rates.service';
-import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
-import { eatDay } from '../train-scheduling/batch-window.util';
-import { BookingOrdersRepository } from './booking-orders.repository';
-import { CreateBookingOrderDto } from './dto/create-booking-order.dto';
-import { BookingOrder } from './entities/booking-order.entity';
-import { BookingOrderLine } from './entities/booking-order-line.entity';
-import { GeneralContractService } from './general-contract.service';
-import { isRoadService, roadKmPrice } from './road.util';
-
-@Injectable()
-export class BookingOrdersService {
-  private readonly logger = new Logger(BookingOrdersService.name);
-
-  constructor(
-    private readonly dataSource: DataSource,
-    private readonly ordersRepository: BookingOrdersRepository,
-    private readonly bookingsRepository: BookingsRepository,
-    private readonly companiesService: CompaniesService,
-    private readonly generalContractService: GeneralContractService,
-    private readonly pricingService: BookingPricingService,
-    private readonly ratesService: RatesService,
-    @Inject(forwardRef(() => TrainSchedulingService))
-    private readonly trainSchedulingService: TrainSchedulingService,
-  ) {}
-
-  /** Orders placed against a contract, with their lines and child booking. */
-  async listByContract(contractBookingId: string): Promise<BookingOrder[]> {
-    const orders = await this.ordersRepository.findByContract(contractBookingId);
-    await Promise.all(orders.map((o) => this.syncOrderFromChild(o)));
-    return orders;
-  }
-
-  async findById(id: string): Promise<BookingOrder | null> {
-    const order = await this.ordersRepository.findById(id);
-    if (order) await this.syncOrderFromChild(order);
-    return order;
-  }
-
-  /**
-   * The order is a ledger row; the spawned child ONE_TIME booking is what
-   * actually moves through the workflow (clearance → marketing/ops accept →
-   * pay → allocate), exactly like a one-time booking. Nothing writes the order
-   * row after creation, so its stored status would stay 'PENDING' forever.
-   *
-   * Mirror the child onto the order whenever it is read: copy the child's
-   * status, schedulingStatus and trainScheduleId onto the order (mutating the
-   * in-memory instance the caller gets back), and persist that snapshot when it
-   * has drifted so list/detail views and any stored reporting stay in sync.
-   */
-  private async syncOrderFromChild(order: BookingOrder): Promise<void> {
-    const child = order.booking;
-    if (!child) return;
-
-    const nextStatus = child.status;
-    const nextScheduling = child.schedulingStatus;
-    const nextTrainScheduleId = child.trainScheduleId ?? null;
-
-    const drifted =
-      order.status !== nextStatus ||
-      order.schedulingStatus !== nextScheduling ||
-      (order.trainScheduleId ?? null) !== nextTrainScheduleId;
-
-    // Reflect the child onto the instance returned to the caller.
-    order.status = nextStatus;
-    order.schedulingStatus = nextScheduling;
-    order.trainScheduleId = nextTrainScheduleId;
-
-    if (drifted) {
-      await this.ordersRepository.update(order.id, {
-        status: nextStatus,
-        schedulingStatus: nextScheduling,
-        trainScheduleId: nextTrainScheduleId,
-      });
-    }
-  }
-
-  /**
-   * Place a drawdown order against an ACTIVE general contract.
-   *
-   * Validates the requested quantities against the remaining pool, then spawns a
-   * ONE_TIME child Booking (PAID + FULLY_EXECUTED, inheriting the contract's
-   * route/cargo/service) so it flows through the existing train-scheduling
-   * pipeline. The order row is the ledger entry linking contract → child booking.
-   */
-  async create(
-    dto: CreateBookingOrderDto,
-    userId?: string,
-  ): Promise<BookingOrder> {
-    const contract = await this.bookingsRepository.findById(dto.contractBookingId);
-    if (!contract) {
-      throw new NotFoundException(`Contract ${dto.contractBookingId} not found`);
-    }
-    if (!this.generalContractService.isGeneralContract(contract)) {
-      throw new BadRequestException('Booking is not a general contract');
-    }
-    if (contract.status !== 'CONTRACT_ACTIVE') {
-      throw new BadRequestException(
-        `Contract is ${contract.status} — orders can only be placed against an ACTIVE contract`,
-      );
-    }
-    if (contract.expiresAt && contract.expiresAt.getTime() <= Date.now()) {
-      throw new BadRequestException('Contract ordering window has expired');
-    }
-
-    // The customer placing the order must own the contract.
-    if (userId && !(await this.userOwnsContract(userId, contract))) {
-      throw new BadRequestException('You do not have access to this contract');
-    }
-
-    // Resolve the route the order ships on: a chosen contract route line for a
-    // multi-route contract, else the contract's own origin/destination.
-    const routeLines = await this.generalContractService.getRouteLines(
-      contract.id,
-    );
-    let originYardId = contract.originYardId;
-    let destinationYardId = contract.destinationYardId;
-    let routeLineId: string | null = null;
-    let routeKm: number | null = null;
-
-    if (routeLines.length > 0) {
-      if (!dto.routeLineId) {
-        throw new BadRequestException(
-          'This contract has multiple routes — select a route to draw from',
-        );
-      }
-      const chosen = routeLines.find((r) => r.routeLineId === dto.routeLineId);
-      if (!chosen) {
-        throw new BadRequestException(
-          'Selected route is not part of this contract',
-        );
-      }
-      originYardId = chosen.originYardId;
-      destinationYardId = chosen.destinationYardId;
-      routeLineId = chosen.routeLineId;
-      routeKm = chosen.km ?? null;
-    }
-
-    // Validate the route has a departure on the chosen day.
-    const day = eatDay(new Date(dto.scheduledDate));
-    const hasDeparture =
-      await this.trainSchedulingService.existsOpenScheduleOnRouteDay(
-        originYardId,
-        destinationYardId,
-        day,
-      );
-    if (!hasDeparture) {
-      throw new BadRequestException(
-        'No departures available on the selected day for this route',
-      );
-    }
-
-    const isContainer = contract.freightType === 'CONTAINER';
-
-    // Hazardous/reefer counts the customer entered cannot exceed the line they
-    // belong to. Validated for every order regardless of routing.
-    for (const line of dto.lines) {
-      const haz = line.hazardousQuantity ?? 0;
-      const reefer = line.reeferQuantity ?? 0;
-      if (haz < 0 || reefer < 0) {
-        throw new BadRequestException('Hazardous/reefer quantities cannot be negative');
-      }
-      if (haz > line.quantity || reefer > line.quantity) {
-        throw new BadRequestException(
-          'Hazardous/reefer quantity cannot exceed the line quantity',
-        );
-      }
-    }
-
-    // The contract has a single shared drawdown pool (per container type for
-    // CONTAINER, or one bulk bucket). Routes are pure lanes — the chosen route
-    // only fixed origin/destination/km above — so every order, routed or not,
-    // validates each line against the same shared pool.
-    const poolLines = await this.generalContractService.getQuantityLines(
-      contract.id,
-    );
-    for (const line of dto.lines) {
-      if (line.quantity <= 0) {
-        throw new BadRequestException('Order quantities must be greater than zero');
-      }
-      const key = isContainer ? (line.containerTypeId ?? '') : '';
-      const poolLine = poolLines.find((p) => (p.containerTypeId ?? '') === key);
-      if (!poolLine) {
-        throw new BadRequestException(
-          isContainer
-            ? `Container type ${line.containerTypeId} is not part of this contract`
-            : 'This contract has no matching quantity pool',
-        );
-      }
-      if (line.quantity > poolLine.remainingQuantity) {
-        throw new BadRequestException(
-          `Requested ${line.quantity} exceeds remaining ${poolLine.remainingQuantity}` +
-            (poolLine.containerTypeName ? ` for ${poolLine.containerTypeName}` : ''),
-        );
-      }
-    }
-
-    // Persist the order + its child shipment booking atomically.
-    const order = await this.dataSource.transaction(async (manager) => {
-      const childBooking = await this.spawnChildBooking(
-        contract,
-        dto,
-        { originYardId, destinationYardId, km: routeKm },
-        manager,
-      );
-
-      const reference = await this.generateReference();
-      const orderRow = manager.create(BookingOrder, {
-        reference,
-        contractBookingId: contract.id,
-        bookingId: childBooking.id,
-        routeLineId,
-        companyId: contract.companyId ?? null,
-        scheduledDate: new Date(dto.scheduledDate),
-        // The order is a ledger row; the child booking drives the workflow
-        // (review → pay → allocate), so the order tracks PENDING until done.
-        status: 'PENDING',
-        schedulingStatus: 'NOT_SCHEDULED',
-      });
-      const savedOrder = await manager.save(orderRow);
-
-      const lines = dto.lines.map((l) =>
-        manager.create(BookingOrderLine, {
-          orderId: savedOrder.id,
-          containerTypeId: isContainer ? (l.containerTypeId ?? null) : null,
-          quantity: l.quantity,
-          hazardousQuantity: l.hazardousQuantity ?? 0,
-          reeferQuantity: l.reeferQuantity ?? 0,
-        }),
-      );
-      await manager.save(lines);
-      savedOrder.lines = lines;
-      return savedOrder;
-    });
-
-    // The child does NOT enter the train batch pool here. It is priced and
-    // unpaid, awaiting Marketing review (OPERATION_REQUEST_PENDING) or customs
-    // clearance first; the batch enqueue happens only on accept.
-
-    // Close the contract once its pool is exhausted (pending orders count, so
-    // the pool reserves quantity as soon as an order is placed).
-    if (await this.generalContractService.isExhausted(contract.id)) {
-      await this.dataSource
-        .getRepository(Booking)
-        .update(contract.id, { status: 'CONTRACT_CLOSED' });
-      this.logger.log(
-        `Contract ${contract.reference} CLOSED — quantity exhausted`,
-      );
-    }
-
-    return (await this.ordersRepository.findById(order.id)) ?? order;
-  }
-
-  /**
-   * Create the ONE_TIME child booking for an order, inheriting the contract's
-   * shipment context. Unlike the contract (which is no longer paid up front),
-   * the child is PRICED and UNPAID and waits for Marketing review — going
-   * through the customs clearance gate first when the service includes customs,
-   * mirroring a one-time booking. It only enters the train pool on accept.
-   */
-  private async spawnChildBooking(
-    contract: Booking,
-    dto: CreateBookingOrderDto,
-    route: { originYardId: string; destinationYardId: string; km: number | null },
-    manager: import('typeorm').EntityManager,
-  ): Promise<Booking> {
-    const reference = await this.generateChildBookingReference();
-    const isContainer = contract.freightType === 'CONTAINER';
-
-    // Sum line quantities × the contract's per-unit weight for the child total.
-    const containerByType = new Map(
-      (contract.bookingContainers ?? []).map((c) => [c.containerTypeId, c]),
-    );
-    let totalWeight = 0;
-    if (isContainer) {
-      for (const line of dto.lines) {
-        const src = containerByType.get(line.containerTypeId ?? '');
-        const vgmPerUnit = src ? Number(src.vgmPerUnitTons) : 0;
-        totalWeight += vgmPerUnit * line.quantity;
-      }
-    } else {
-      totalWeight = dto.lines.reduce((sum, l) => sum + l.quantity, 0);
-    }
-
-    // Per-order hazardous/reefer: set the child flags from the order's line
-    // counts so the HAZARD_SURCHARGE / REEFER_SURCHARGE rates apply.
-    const hasHazardous = dto.lines.some((l) => (l.hazardousQuantity ?? 0) > 0);
-    const hasReefer = dto.lines.some((l) => (l.reeferQuantity ?? 0) > 0);
-
-    // Customs orders flow through the one-time clearance gate first; others go
-    // straight to operations review with the chosen shipment day.
-    const { includesCustoms } = clearanceCodesForBooking(contract);
-    const spawnStatus = includesCustoms
-      ? 'AWAITING_DOCUMENTS'
-      : 'OPERATION_REQUEST_PENDING';
-
-    const child = manager.create(Booking, {
-      reference,
-      // Drawdown orders inherit the contract's company + profile (both required).
-      companyId: contract.companyId,
-      companyProfileId: contract.companyProfileId,
-      isGovernment: contract.isGovernment,
-      governmentInstitution: contract.governmentInstitution ?? null,
-      contractType: contract.contractType,
-      previousContractId: contract.id,
-      serviceTypeId: contract.serviceTypeId,
-      firstMilePickupAddress: contract.firstMilePickupAddress ?? null,
-      lastMileDeliveryAddress: contract.lastMileDeliveryAddress ?? null,
-      equipmentReturn: contract.equipmentReturn,
-      originYardId: route.originYardId,
-      destinationYardId: route.destinationYardId,
-      tradeDirection: contract.tradeDirection,
-      freightType: contract.freightType,
-      cargoTypeId: contract.cargoTypeId ?? null,
-      cargoFreeText: contract.cargoFreeText ?? null,
-      shippingLineId: contract.shippingLineId ?? null,
-      cargoTotalWeightVgm: totalWeight,
-      isHazardous: hasHazardous,
-      isReefer: hasReefer,
-      paymentCurrency: contract.paymentCurrency,
-      bookingType: 'ONE_TIME',
-      scheduledDate: new Date(dto.scheduledDate),
-      // Priced + unpaid: the customer pays this order on its own.
-      status: spawnStatus,
-      paymentStatus: 'PENDING',
-      priorityScore: contract.priorityScore,
-      totalAmount: 0,
-      schedulingStatus: 'NOT_SCHEDULED',
-    });
-    const savedChild = await manager.save(child);
-
-    if (isContainer) {
-      for (const line of dto.lines) {
-        const src = containerByType.get(line.containerTypeId ?? '');
-        const ct = line.containerTypeId
-          ? await manager.getRepository(ContainerType).findOne({
-              where: { id: line.containerTypeId },
-            })
-          : null;
-        const wagonsPerUnit = ct ? Number(ct.wagonsPerUnit) : 1;
-        const vgmPerUnit = src ? Number(src.vgmPerUnitTons) : 0;
-        const row = manager.create(BookingContainer, {
-          bookingId: savedChild.id,
-          containerTypeId: line.containerTypeId ?? null,
-          quantity: line.quantity,
-          vgmPerUnitTons: vgmPerUnit,
-          totalVgmTons: vgmPerUnit * line.quantity,
-          wagonsRequired: Math.ceil(line.quantity * wagonsPerUnit),
-          isOverweight: false,
-        });
-        await manager.save(row);
-      }
-    }
-
-    // Price the order: base freight for the drawn quantity + haz/reefer
-    // surcharges, plus a road KM charge when the service ships by road.
-    const roadKm = isRoadService(contract.serviceType) ? route.km : null;
-    await this.priceChildBooking(savedChild.id, roadKm, manager);
-
-    return savedChild;
-  }
-
-  /**
-   * Compute and persist the child order's price (base + surcharges) inside the
-   * order transaction. The contract is no longer paid up front, so each order
-   * carries its own total that the customer pays.
-   */
-  private async priceChildBooking(
-    childId: string,
-    roadKm: number | null,
-    manager: import('typeorm').EntityManager,
-  ): Promise<void> {
-    const child = await manager.getRepository(Booking).findOne({
-      where: { id: childId },
-      relations: { bookingContainers: true },
-    });
-    if (!child) return;
-
-    try {
-      const computed = await this.pricingService.computePriceForBooking(child);
-      const lineItems = [...computed.lineItems];
-      let total = computed.totalAmount;
-
-      // Road KM charge: distance × the live PER_KM rate, added as its own line.
-      if (roadKm && roadKm > 0) {
-        const perKmRate = await this.findPerKmRate(child.paymentCurrency);
-        const kmAmount = roadKmPrice(roadKm, perKmRate);
-        if (kmAmount > 0) {
-          lineItems.push({
-            code: 'ROAD_KM',
-            description: `Road transport (${roadKm} km)`,
-            amount: kmAmount,
-            unitAmount: perKmRate!,
-            unit: 'PER_KM',
-            quantity: roadKm,
-            currency: child.paymentCurrency,
-          });
-          total += kmAmount;
-        }
-      }
-
-      await manager.getRepository(Booking).update(childId, {
-        totalAmount: total,
-        priorityScore: computed.priorityScore,
-        pricingBreakdown: {
-          lineItems,
-          totalAmount: total,
-          currency: computed.currency,
-          generatedAt: new Date().toISOString(),
-        },
-      } as never);
-    } catch (err) {
-      this.logger.error(
-        `Pricing child order ${childId} failed: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
-  /** The live PER_KM rate value for road billing, in the given currency. */
-  private async findPerKmRate(currency: string): Promise<number | null> {
-    const rates = await this.ratesService.findLiveRates();
-    const rate = rates.find(
-      (r) => r.rateUnit === 'PER_KM' && r.currency === currency,
-    );
-    return rate ? Number(rate.rateValue) : null;
-  }
-
-  private async userOwnsContract(
-    userId: string,
-    contract: Booking,
-  ): Promise<boolean> {
-    if (!contract.companyId) return true; // government / staff-created
-    try {
-      const { company } = await this.companiesService.getCompanyInfoByUserId(
-        userId,
-      );
-      return company.id === contract.companyId;
-    } catch {
-      return false;
-    }
-  }
-
-  private async generateReference(): Promise<string> {
-    const year = new Date().getFullYear();
-    const count = await this.ordersRepository.countByYear(year);
-    return `ORD-${year}-${String(count + 1).padStart(6, '0')}`;
-  }
-
-  private async generateChildBookingReference(): Promise<string> {
-    const year = new Date().getFullYear();
-    const count = await this.bookingsRepository.countByYear(year);
-    return `BK-${year}-${String(count + 1).padStart(6, '0')}`;
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
index 4eacedc13..6cd2f4be5 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
@@ -52,7 +52,7 @@ export class BookingInvoiceService {
     private readonly firstMile: FirstMileService,
     @Inject(forwardRef(() => BookingBatchService))
     private readonly bookingBatch: BookingBatchService,
-  ) {}
+  ) { }
 
   /**
    * Ensure the booking has its invoice, generating one from the snapshotted
@@ -122,7 +122,8 @@ export class BookingInvoiceService {
     if (booking.paymentStatus === 'PAID') return;
 
     const paidAt = new Date();
-    const isGeneralContract = booking.bookingType === 'GENERAL_CONTRACT';
+    const isGeneralContract = false
+    // booking.bookingType === 'GENERAL_CONTRACT';
 
     let contractExpiresAt: Date | null = null;
     if (isGeneralContract) {

From 0b1e33045912c4ea94bd0c2539d048ad5910967c Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 29 Jun 2026 13:00:55 +0000
Subject: [PATCH 14/63] add payemnt test

---
 apps/edr-freight-api/html/payment-tester.html | 452 ++++++++++++++++++
 1 file changed, 452 insertions(+)
 create mode 100644 apps/edr-freight-api/html/payment-tester.html

diff --git a/apps/edr-freight-api/html/payment-tester.html b/apps/edr-freight-api/html/payment-tester.html
new file mode 100644
index 000000000..1bb1a5c80
--- /dev/null
+++ b/apps/edr-freight-api/html/payment-tester.html
@@ -0,0 +1,452 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>EDR Freight — Payment Tester (Telebirr ETB + Card USD)</title>
+<style>
+  :root {
+    --bg: #0f1419;
+    --panel: #1a2129;
+    --panel-2: #232d38;
+    --border: #2e3b48;
+    --txt: #e6edf3;
+    --muted: #8b98a5;
+    --accent: #1a73e8;
+    --etb: #00a651;      /* telebirr green */
+    --usd: #2563eb;      /* card blue */
+    --ok: #2ea043;
+    --warn: #d29922;
+    --err: #f85149;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    background: var(--bg); color: var(--txt); line-height: 1.5;
+  }
+  header {
+    padding: 20px 24px; border-bottom: 1px solid var(--border);
+    background: var(--panel); display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
+  }
+  header h1 { font-size: 1.05rem; margin: 0; font-weight: 600; }
+  header .badge {
+    font-size: .7rem; padding: 2px 8px; border-radius: 999px;
+    background: var(--panel-2); color: var(--muted); border: 1px solid var(--border);
+  }
+  main { max-width: 920px; margin: 0 auto; padding: 24px; display: grid; gap: 20px; }
+  .card {
+    background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 20px;
+  }
+  .card h2 { margin: 0 0 14px; font-size: .8rem; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }
+  label { display: block; font-size: .78rem; color: var(--muted); margin: 0 0 6px; }
+  input, select {
+    width: 100%; padding: 10px 12px; border-radius: 8px; border: 1px solid var(--border);
+    background: var(--panel-2); color: var(--txt); font-size: .9rem; font-family: inherit;
+  }
+  input:focus, select:focus { outline: none; border-color: var(--accent); }
+  .row { display: grid; grid-template-columns: 1fr auto; gap: 10px; align-items: end; }
+  .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
+  button {
+    cursor: pointer; border: none; border-radius: 8px; padding: 10px 16px;
+    font-size: .85rem; font-weight: 600; color: #fff; font-family: inherit;
+    background: var(--panel-2); border: 1px solid var(--border); color: var(--txt);
+    transition: filter .15s, opacity .15s;
+  }
+  button:hover:not(:disabled) { filter: brightness(1.15); }
+  button:disabled { opacity: .45; cursor: not-allowed; }
+  button.pay-etb { background: var(--etb); border-color: var(--etb); color: #fff; }
+  button.pay-usd { background: var(--usd); border-color: var(--usd); color: #fff; }
+  button.ghost { background: transparent; }
+  .pay-buttons { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin-top: 4px; }
+  .pay-buttons button { padding: 16px; font-size: .95rem; display: flex; flex-direction: column; gap: 4px; align-items: center; }
+  .pay-buttons button small { font-weight: 400; opacity: .85; font-size: .72rem; }
+  .booking-meta { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 12px; margin-top: 14px; }
+  .meta-item { background: var(--panel-2); border: 1px solid var(--border); border-radius: 8px; padding: 10px 12px; }
+  .meta-item .k { font-size: .68rem; color: var(--muted); text-transform: uppercase; letter-spacing: .04em; }
+  .meta-item .v { font-size: 1rem; font-weight: 600; margin-top: 2px; word-break: break-all; }
+  .pill { display: inline-block; font-size: .72rem; font-weight: 600; padding: 2px 9px; border-radius: 999px; }
+  .pill.etb { background: rgba(0,166,81,.15); color: #4ade80; }
+  .pill.usd { background: rgba(37,99,235,.18); color: #60a5fa; }
+  .status-line { display: flex; align-items: center; gap: 8px; font-size: .9rem; }
+  .dot { width: 9px; height: 9px; border-radius: 50%; background: var(--muted); }
+  .dot.ok { background: var(--ok); } .dot.warn { background: var(--warn); } .dot.err { background: var(--err); }
+  .dot.pulse { animation: pulse 1s ease-in-out infinite; }
+  @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: .3; } }
+  pre {
+    background: #0b0f14; border: 1px solid var(--border); border-radius: 8px; padding: 14px;
+    font-size: .76rem; overflow: auto; max-height: 320px; margin: 10px 0 0; color: #c9d1d9;
+  }
+  .log { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: .74rem; }
+  .log-entry { padding: 4px 0; border-bottom: 1px solid var(--border); }
+  .log-entry .ts { color: var(--muted); margin-right: 8px; }
+  .log-entry.req { color: #79c0ff; } .log-entry.res { color: #7ee787; } .log-entry.err { color: var(--err); }
+  .actions { display: flex; gap: 10px; flex-wrap: wrap; margin-top: 14px; }
+  .hint { font-size: .76rem; color: var(--muted); margin-top: 8px; }
+  a { color: #58a6ff; }
+  .table { width: 100%; border-collapse: collapse; font-size: .8rem; margin-top: 10px; }
+  .table th, .table td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--border); }
+  .table th { color: var(--muted); font-weight: 500; font-size: .72rem; text-transform: uppercase; }
+  .table tr.clickable { cursor: pointer; }
+  .table tr.clickable:hover { background: var(--panel-2); }
+  .split { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+  @media (max-width: 720px) { .split, .grid-2, .pay-buttons { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<header>
+  <h1>🚂 EDR Freight — Payment Tester</h1>
+  <span class="badge">Telebirr (ETB)</span>
+  <span class="badge">Card (USD)</span>
+</header>
+
+<main>
+  <!-- ── Config ───────────────────────────────────────────── -->
+  <section class="card">
+    <h2>API connection</h2>
+    <div class="grid-2">
+      <div>
+        <label>API base URL</label>
+        <input id="apiBase" value="http://localhost:3001/api" />
+      </div>
+      <div>
+        <label>Service / Bearer token (optional)</label>
+        <input id="token" placeholder="Bearer token if guards enabled" />
+      </div>
+    </div>
+    <div class="actions">
+      <button class="ghost" id="pingBtn">Test connection</button>
+      <span class="status-line"><span class="dot" id="pingDot"></span><span id="pingTxt">not checked</span></span>
+    </div>
+  </section>
+
+  <!-- ── Pick booking ─────────────────────────────────────── -->
+  <section class="card">
+    <h2>1 · Choose a booking</h2>
+    <div class="row">
+      <div>
+        <label>Booking ID (UUID) — paste directly, or load the list below</label>
+        <input id="bookingId" placeholder="e.g. 9f8c…-uuid" />
+      </div>
+      <button class="ghost" id="loadBookingBtn">Load this booking</button>
+    </div>
+    <div class="actions">
+      <button class="ghost" id="listBtn">List recent bookings</button>
+      <span class="hint">Currency (ETB vs USD) is set per-booking via <code>paymentCurrency</code>. Pick an ETB booking to test Telebirr, a USD booking to test Card.</span>
+    </div>
+    <div id="bookingList"></div>
+
+    <div id="bookingMeta" style="display:none;">
+      <div class="booking-meta">
+        <div class="meta-item"><div class="k">Reference</div><div class="v" id="mRef">—</div></div>
+        <div class="meta-item"><div class="k">Amount</div><div class="v" id="mAmt">—</div></div>
+        <div class="meta-item"><div class="k">Currency</div><div class="v" id="mCur">—</div></div>
+        <div class="meta-item"><div class="k">Status</div><div class="v" id="mStatus">—</div></div>
+        <div class="meta-item"><div class="k">Pay status</div><div class="v" id="mPay">—</div></div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Pay ──────────────────────────────────────────────── -->
+  <section class="card">
+    <h2>2 · Initiate payment</h2>
+    <div class="grid-2">
+      <div>
+        <label>Platform</label>
+        <select id="platform"><option value="web">web (browser redirect)</option><option value="mobile">mobile (launch app)</option></select>
+      </div>
+      <div>
+        <label>Payer account (optional — Waafi MWALLET / phone)</label>
+        <input id="payerAccount" placeholder="2519…" />
+      </div>
+    </div>
+    <div class="pay-buttons">
+      <button class="pay-etb" id="payTelebirr" disabled>Pay with Telebirr<small>ETB · Ethiopian mobile money</small></button>
+      <button class="pay-usd" id="payCard" disabled>Pay with Card<small>USD · Visa / Mastercard</small></button>
+    </div>
+    <div class="actions" style="margin-top:14px;">
+      <label style="margin:0;display:flex;align-items:center;gap:6px;font-size:.8rem;">
+        <input type="checkbox" id="openTab" checked style="width:auto;" /> open provider checkout in new tab
+      </label>
+    </div>
+    <div class="hint">
+      Telebirr → forces method <code>TELEBIRR</code>. Card → forces method <code>CARD</code>.
+      Each calls <code>POST {base}/payments/initiate</code> and follows the returned <code>clientAction</code> (REDIRECT url for web).
+    </div>
+    <p class="hint" id="initiateResult"></p>
+  </section>
+
+  <!-- ── Status / receipt ─────────────────────────────────── -->
+  <section class="card">
+    <h2>3 · Track intent &amp; receipt</h2>
+    <div class="actions">
+      <button class="ghost" id="pollBtn" disabled>Refresh intent status</button>
+      <label style="margin:0;display:flex;align-items:center;gap:6px;font-size:.8rem;">
+        <input type="checkbox" id="autoPoll" style="width:auto;" /> auto-poll every 3s
+      </label>
+      <span class="status-line"><span class="dot" id="intentDot"></span><span id="intentTxt">no intent yet</span></span>
+    </div>
+    <div class="actions" style="margin-top:6px;">
+      <button class="ghost" id="receiptBtn" disabled>Open receipt (success only)</button>
+      <span class="hint">Receipt = <code>GET {base}/payments/receipt/{merchantOrderId}</code></span>
+    </div>
+  </section>
+
+  <!-- ── Raw / log ────────────────────────────────────────── -->
+  <section class="split">
+    <div class="card">
+      <h2>Last response</h2>
+      <pre id="rawOut">—</pre>
+    </div>
+    <div class="card">
+      <h2>Request log</h2>
+      <div class="log" id="log"></div>
+    </div>
+  </section>
+</main>
+
+<script>
+(function () {
+  "use strict";
+
+  const $ = (id) => document.getElementById(id);
+  const state = { booking: null, intent: null, merchantOrderId: null, pollTimer: null };
+
+  // ── helpers ─────────────────────────────────────────────
+  const base = () => $("apiBase").value.replace(/\/$/, "");
+  const headers = () => {
+    const h = { "Content-Type": "application/json", Accept: "application/json" };
+    const t = $("token").value.trim();
+    if (t) h["Authorization"] = t.startsWith("Bearer ") ? t : "Bearer " + t;
+    return h;
+  };
+
+  function now() {
+    const d = new Date();
+    return d.toTimeString().slice(0, 8) + "." + String(d.getMilliseconds()).padStart(3, "0");
+  }
+  function log(kind, msg) {
+    const el = document.createElement("div");
+    el.className = "log-entry " + kind;
+    el.innerHTML = '<span class="ts">' + now() + "</span>" + msg;
+    $("log").prepend(el);
+  }
+  function showRaw(obj) {
+    $("rawOut").textContent = typeof obj === "string" ? obj : JSON.stringify(obj, null, 2);
+  }
+  function setDot(id, cls) {
+    const d = $(id);
+    d.className = "dot" + (cls ? " " + cls : "");
+  }
+
+  // Unwrap the @edr/api-common ResponseTransformInterceptor envelope if present.
+  function unwrap(json) {
+    if (json && typeof json === "object" && "data" in json && ("statusCode" in json || "success" in json)) {
+      return json.data;
+    }
+    return json;
+  }
+
+  async function api(method, path, body) {
+    const url = base() + path;
+    log("req", method + " " + path);
+    let res, text, json;
+    try {
+      res = await fetch(url, {
+        method,
+        headers: headers(),
+        body: body ? JSON.stringify(body) : undefined,
+      });
+    } catch (e) {
+      log("err", "network error: " + e.message + " — is the API running at " + base() + "?");
+      throw e;
+    }
+    text = await res.text();
+    try { json = text ? JSON.parse(text) : null; } catch { json = text; }
+    if (!res.ok) {
+      const detail = json && json.message ? (Array.isArray(json.message) ? json.message.join(", ") : json.message) : text;
+      log("err", method + " " + path + " → " + res.status + ": " + detail);
+      showRaw(json || text);
+      throw new Error(detail || ("HTTP " + res.status));
+    }
+    log("res", method + " " + path + " → " + res.status);
+    return unwrap(json);
+  }
+
+  // ── ping ────────────────────────────────────────────────
+  $("pingBtn").onclick = async () => {
+    setDot("pingDot", "pulse warn"); $("pingTxt").textContent = "checking…";
+    try {
+      // payment summary is a light, low-side-effect GET
+      await api("GET", "/payments/summary");
+      setDot("pingDot", "ok"); $("pingTxt").textContent = "connected ✓";
+    } catch (e) {
+      setDot("pingDot", "err"); $("pingTxt").textContent = "failed — " + e.message;
+    }
+  };
+
+  // ── list bookings ───────────────────────────────────────
+  $("listBtn").onclick = async () => {
+    try {
+      const data = await api("GET", "/bookings");
+      const items = Array.isArray(data) ? data : (data && data.items) || [];
+      renderBookingList(items.slice(0, 25));
+    } catch (e) { /* logged */ }
+  };
+
+  function renderBookingList(items) {
+    const wrap = $("bookingList");
+    if (!items.length) { wrap.innerHTML = '<p class="hint">No bookings returned.</p>'; return; }
+    let html = '<table class="table"><thead><tr><th>Reference</th><th>Amount</th><th>Cur</th><th>Status</th><th>ID</th></tr></thead><tbody>';
+    for (const b of items) {
+      const cur = b.paymentCurrency || b.currency || "—";
+      const curClass = cur === "ETB" ? "etb" : cur === "USD" ? "usd" : "";
+      const amt = b.totalAmount != null ? b.totalAmount : (b.amount != null ? b.amount : "—");
+      html += '<tr class="clickable" data-id="' + (b.id || "") + '">' +
+        "<td>" + (b.reference || "—") + "</td>" +
+        "<td>" + amt + "</td>" +
+        '<td><span class="pill ' + curClass + '">' + cur + "</span></td>" +
+        "<td>" + (b.status || "—") + "</td>" +
+        '<td style="font-size:.7rem;color:var(--muted);">' + (b.id ? b.id.slice(0, 8) + "…" : "—") + "</td></tr>";
+    }
+    html += "</tbody></table>";
+    wrap.innerHTML = html;
+    wrap.querySelectorAll("tr.clickable").forEach((tr) => {
+      tr.onclick = () => { $("bookingId").value = tr.dataset.id; loadBooking(); };
+    });
+  }
+
+  // ── load one booking ────────────────────────────────────
+  $("loadBookingBtn").onclick = loadBooking;
+  async function loadBooking() {
+    const id = $("bookingId").value.trim();
+    if (!id) { log("err", "enter a booking ID first"); return; }
+    try {
+      const b = await api("GET", "/bookings/" + id);
+      state.booking = b;
+      showRaw(b);
+      renderMeta(b);
+      enablePayButtons(b);
+      $("pollBtn").disabled = false;
+      // pre-load any existing intent
+      refreshIntent(true).catch(() => {});
+    } catch (e) { /* logged */ }
+  }
+
+  function renderMeta(b) {
+    const cur = b.paymentCurrency || b.currency || "—";
+    $("bookingMeta").style.display = "block";
+    $("mRef").textContent = b.reference || "—";
+    $("mAmt").textContent = (b.totalAmount != null ? b.totalAmount : (b.amount != null ? b.amount : "—"));
+    $("mCur").innerHTML = '<span class="pill ' + (cur === "ETB" ? "etb" : cur === "USD" ? "usd" : "") + '">' + cur + "</span>";
+    $("mStatus").textContent = b.status || "—";
+    $("mPay").textContent = b.paymentStatus || "—";
+  }
+
+  function enablePayButtons(b) {
+    const cur = b.paymentCurrency || b.currency || "";
+    const etbBtn = $("payTelebirr"), usdBtn = $("payCard");
+    etbBtn.disabled = false; usdBtn.disabled = false;
+    // soft hint via title; both stay enabled so you can deliberately test mismatch
+    etbBtn.title = cur && cur !== "ETB" ? "Booking currency is " + cur + ", not ETB — Telebirr expects ETB" : "";
+    usdBtn.title = cur && cur !== "USD" ? "Booking currency is " + cur + ", not USD — Card expects USD" : "";
+  }
+
+  // ── initiate payment ────────────────────────────────────
+  async function pay(method, label) {
+    const id = $("bookingId").value.trim();
+    if (!id) { log("err", "pick a booking first"); return; }
+    $("initiateResult").textContent = "Initiating " + label + "…";
+    const body = {
+      bookingId: id,
+      method: method,
+      platform: $("platform").value,
+    };
+    const payer = $("payerAccount").value.trim();
+    if (payer) body.payerAccount = payer;
+
+    try {
+      const resp = await api("POST", "/payments/initiate", body);
+      state.intent = resp;
+      state.merchantOrderId = resp.merchantOrderId || null;
+      showRaw(resp);
+      renderIntent(resp);
+      $("receiptBtn").disabled = !state.merchantOrderId;
+
+      const action = resp.clientAction;
+      if (action && action.type === "REDIRECT" && action.url) {
+        $("initiateResult").innerHTML =
+          label + " intent created (status: " + resp.status + "). " +
+          'Redirect → <a href="' + action.url + '" target="_blank" rel="noopener">' + action.url + "</a>";
+        if ($("openTab").checked) window.open(action.url, "_blank", "noopener");
+      } else if (action && action.type === "LAUNCH_APP") {
+        $("initiateResult").textContent =
+          label + " → LAUNCH_APP (mobile). appId=" + (action.appId || "") + " shortCode=" + (action.shortCode || "");
+      } else if (action && action.type === "COLLECT_OTP") {
+        $("initiateResult").textContent =
+          label + " → COLLECT_OTP. providerOrderId=" + (action.providerOrderId || "") + " — " + (action.message || "");
+      } else {
+        $("initiateResult").textContent = label + " intent created. Status: " + resp.status + " (no redirect action).";
+      }
+      // begin watching
+      if ($("autoPoll").checked) startAutoPoll();
+    } catch (e) {
+      $("initiateResult").textContent = "Failed: " + e.message;
+    }
+  }
+  $("payTelebirr").onclick = () => pay("TELEBIRR", "Telebirr (ETB)");
+  $("payCard").onclick = () => pay("CARD", "Card (USD)");
+
+  // ── intent status ───────────────────────────────────────
+  $("pollBtn").onclick = () => refreshIntent(false);
+  async function refreshIntent(silent) {
+    const id = $("bookingId").value.trim();
+    if (!id) return;
+    try {
+      const resp = await api("GET", "/payments/intents/" + id);
+      state.intent = resp;
+      if (resp.merchantOrderId) state.merchantOrderId = resp.merchantOrderId;
+      $("receiptBtn").disabled = !state.merchantOrderId;
+      showRaw(resp);
+      renderIntent(resp);
+      return resp;
+    } catch (e) {
+      if (!silent) { /* already logged */ }
+    }
+  }
+
+  function renderIntent(resp) {
+    const s = (resp.status || "").toUpperCase();
+    let cls = "warn";
+    if (s === "SUCCEEDED") cls = "ok";
+    else if (s === "FAILED" || s === "CANCELLED") cls = "err";
+    setDot("intentDot", cls);
+    let txt = "status: " + (resp.status || "—");
+    if (resp.merchantOrderId) txt += " · order " + resp.merchantOrderId;
+    if (resp.paidAt) txt += " · paid " + resp.paidAt;
+    if (resp.failureMessage) txt += " · " + resp.failureMessage;
+    $("intentTxt").textContent = txt;
+    if (s === "SUCCEEDED" || s === "FAILED" || s === "CANCELLED") stopAutoPoll();
+  }
+
+  function startAutoPoll() {
+    stopAutoPoll();
+    state.pollTimer = setInterval(() => refreshIntent(true), 3000);
+  }
+  function stopAutoPoll() {
+    if (state.pollTimer) { clearInterval(state.pollTimer); state.pollTimer = null; }
+  }
+  $("autoPoll").onchange = (e) => { if (e.target.checked) startAutoPoll(); else stopAutoPoll(); };
+
+  // ── receipt ─────────────────────────────────────────────
+  $("receiptBtn").onclick = () => {
+    if (!state.merchantOrderId) { log("err", "no merchantOrderId yet — pay first"); return; }
+    const url = base() + "/payments/receipt/" + encodeURIComponent(state.merchantOrderId);
+    log("req", "GET /payments/receipt/" + state.merchantOrderId + " (new tab)");
+    window.open(url, "_blank", "noopener");
+  };
+
+  log("res", "ready — set API base, pick a booking, pay with Telebirr (ETB) or Card (USD)");
+})();
+</script>
+</body>
+</html>

From f7f0f6aef3b60b5dc3ecd4ddcbf9b2de187d3304 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 13:45:35 +0000
Subject: [PATCH 15/63] fix: update the invoice generation to the new booking
 creation

---
 .../src/modules/bookings/bookings.module.ts   |  2 +-
 .../contracts/contract-booking.service.ts     | 21 +++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 2e968309f..1a12a5e6f 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -86,6 +86,6 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
     ContractRendererService,
     ContractPdfService,
   ],
-  exports: [BookingsService, BookingsRepository, BookingPricingService],
+  exports: [BookingsService, BookingsRepository, BookingPricingService, BookingInvoiceService],
 })
 export class BookingsModule {}
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index 808fd8a63..b077930b7 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -2,6 +2,7 @@ import {
   BadRequestException,
   ForbiddenException,
   Injectable,
+  Logger,
   NotFoundException,
 } from '@nestjs/common';
 import { DataSource } from 'typeorm';
@@ -11,6 +12,7 @@ import { BookingContainer } from '../bookings/entities/booking-container.entity'
 import { BookingContainerUnit } from '../bookings/entities/booking-container-unit.entity';
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { BookingPricingService } from '../bookings/booking-pricing.service';
+import { BookingInvoiceService } from '../bookings/booking-invoice.service';
 import { ContainerTypesService } from '../rule-engine/services/container-types.service';
 import { RuleEngineService } from '../rule-engine/rule-engine.service';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
@@ -45,6 +47,8 @@ export interface CreateBookingUnderContractResult {
  */
 @Injectable()
 export class ContractBookingService {
+  private readonly logger = new Logger(ContractBookingService.name);
+
   constructor(
     private readonly contractsRepository: ContractsRepository,
     private readonly bookingsRepository: BookingsRepository,
@@ -52,6 +56,7 @@ export class ContractBookingService {
     private readonly containerTypesService: ContainerTypesService,
     private readonly ruleEngineService: RuleEngineService,
     private readonly milestoneService: ClearanceMilestoneService,
+    private readonly invoiceService: BookingInvoiceService,
     private readonly dataSource: DataSource,
   ) {}
 
@@ -199,6 +204,22 @@ export class ContractBookingService {
     }
 
     const result = await this.bookingsRepository.findByIdWithFiles(booking.id);
+
+    // Contract bookings are born past the billable gate (the contract is already
+    // executed), so the invoice is generated here — they never pass through the
+    // legacy marketingApprove → FULLY_EXECUTED path that invoices direct bookings.
+    // Idempotent and non-blocking: a billing hiccup must not undo the booking.
+    // Skips silently when unbillable (no company / no priced amount).
+    await this.invoiceService
+      .ensureInvoiceForBooking(result ?? booking)
+      .catch((err) =>
+        this.logger.error(
+          `Failed to generate invoice for contract booking ${booking.reference}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        ),
+      );
+
     return { booking: result ?? booking, warnings };
   }
 

From f2826f2b9b05473888d763b364da71ee883f72ed Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 13:49:01 +0000
Subject: [PATCH 16/63] fix

---
 apps/edr-freight-api/Dockerfile   | 2 +-
 apps/edr-freight-api/package.json | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/Dockerfile b/apps/edr-freight-api/Dockerfile
index b0850737b..a9965c74a 100644
--- a/apps/edr-freight-api/Dockerfile
+++ b/apps/edr-freight-api/Dockerfile
@@ -34,4 +34,4 @@ RUN addgroup --system --gid 1001 nodejs \
 COPY --from=deployer --chown=nestjs:nodejs /deploy .
 USER nestjs
 EXPOSE 3001
-CMD ["node", "dist/main.js"]
+CMD ["sh", "-c", "pnpm run migrate && node dist/main.js"]
diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index 27737c84c..df84d0c35 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -29,7 +29,8 @@
     "iam:migration:run": "pnpm run iam:typeorm:cli migration:run",
     "iam:migration:revert": "pnpm run iam:typeorm:cli migration:revert",
     "iam:migration:show": "pnpm run iam:typeorm:cli migration:show",
-    "iam:seed:run": "cross-env APP_MODULE_PATH=./dist/app.module dotenv -- node ./node_modules/@tria-plc/iamapi-common/dist/db/seed.cli.js"
+    "iam:seed:run": "cross-env APP_MODULE_PATH=./dist/app.module dotenv -- node ./node_modules/@tria-plc/iamapi-common/dist/db/seed.cli.js",
+    "migrate": "ts-node -r tsconfig-paths/register src/scripts/run-migrations.ts"
   },
   "dependencies": {
     "@edr/api-common": "workspace:*",

From 8b6b6ec7375f90f9a8b43b949056568762440dc8 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 13:52:54 +0000
Subject: [PATCH 17/63] fix

---
 ...667261000-AddPostPaymentCompletedColumn.ts | 46 +++++++++++++++++--
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts b/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts
index b7846bac9..c755d6356 100644
--- a/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts
+++ b/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts
@@ -1,15 +1,51 @@
-import { MigrationInterface, QueryRunner } from 'typeorm';
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
 
 export class AddPostPaymentCompletedColumn1719667261000 implements MigrationInterface {
   name = 'AddPostPaymentCompletedColumn1719667261000';
 
   public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`ALTER TABLE freight.first_mile_deliveries ADD COLUMN IF NOT EXISTS is_post_payment_completed BOOLEAN NOT NULL DEFAULT false;`);
-    await queryRunner.query(`ALTER TABLE freight.last_mile_deliveries ADD COLUMN IF NOT EXISTS is_post_payment_completed BOOLEAN NOT NULL DEFAULT false;`);
+    const firstMileTable = await queryRunner.hasTable('freight.first_mile_deliveries');
+    if (firstMileTable) {
+      const hasColumn = await queryRunner.hasColumn('freight.first_mile_deliveries', 'is_post_payment_completed');
+      if (!hasColumn) {
+        await queryRunner.addColumn(
+          'freight.first_mile_deliveries',
+          new TableColumn({
+            name: 'is_post_payment_completed',
+            type: 'boolean',
+            default: false,
+            isNullable: false,
+          })
+        );
+      }
+    }
+
+    const lastMileTable = await queryRunner.hasTable('freight.last_mile_deliveries');
+    if (lastMileTable) {
+      const hasColumn = await queryRunner.hasColumn('freight.last_mile_deliveries', 'is_post_payment_completed');
+      if (!hasColumn) {
+        await queryRunner.addColumn(
+          'freight.last_mile_deliveries',
+          new TableColumn({
+            name: 'is_post_payment_completed',
+            type: 'boolean',
+            default: false,
+            isNullable: false,
+          })
+        );
+      }
+    }
   }
 
   public async down(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`ALTER TABLE freight.last_mile_deliveries DROP COLUMN IF EXISTS is_post_payment_completed;`);
-    await queryRunner.query(`ALTER TABLE freight.first_mile_deliveries DROP COLUMN IF EXISTS is_post_payment_completed;`);
+    const lastMileTable = await queryRunner.hasTable('freight.last_mile_deliveries');
+    if (lastMileTable) {
+      await queryRunner.dropColumn('freight.last_mile_deliveries', 'is_post_payment_completed');
+    }
+
+    const firstMileTable = await queryRunner.hasTable('freight.first_mile_deliveries');
+    if (firstMileTable) {
+      await queryRunner.dropColumn('freight.first_mile_deliveries', 'is_post_payment_completed');
+    }
   }
 }

From 69955bc0e620606a5d5467a23d232d444bfa4879 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 13:53:32 +0000
Subject: [PATCH 18/63] feat: setup the invoice backend

---
 .../src/modules/billing/billing.module.ts     |  5 +-
 .../modules/billing/billing.service.spec.ts   |  5 ++
 .../src/modules/billing/billing.service.ts    | 69 +++++++++++++++++++
 .../modules/billing/dto/pay-invoice.dto.ts    | 30 ++++++++
 .../billing/portal-billing.controller.ts      | 60 ++++++++++++++++
 5 files changed, 168 insertions(+), 1 deletion(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/dto/pay-invoice.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/portal-billing.controller.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 1ed135bbb..551fae6bf 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -2,19 +2,22 @@ import { forwardRef, Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { BillingController } from "./billing.controller";
+import { PortalBillingController } from "./portal-billing.controller";
 import { BillingService } from "./billing.service";
 import { Invoice } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
 import { PaymentModule } from "../payment/payment.module";
+import { CompaniesModule } from "../companies/companies.module";
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([Invoice, InvoiceLine]),
     forwardRef(() => PaymentModule),
+    CompaniesModule,
   ],
-  controllers: [BillingController],
+  controllers: [BillingController, PortalBillingController],
   providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
   exports: [BillingService],
 })
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 907aeb76d..0e6d97de0 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -75,6 +75,7 @@ describe("BillingService.generateInvoice", () => {
       {} as never,
       events as never,
       {} as never, // payment
+      {} as never, // companies
     );
   });
 
@@ -132,6 +133,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never,
       events as never,
       {} as never, // payment
+      {} as never, // companies
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -168,6 +170,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never,
       events as never,
       {} as never, // payment
+      {} as never, // companies
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -196,6 +199,7 @@ describe("BillingService.settlePayable", () => {
       {} as never,
       events as never,
       {} as never, // payment
+      {} as never, // companies
     );
 
     const settled = await service.settlePayable(
@@ -229,6 +233,7 @@ describe("BillingService.settlePayable", () => {
       {} as never,
       events as never,
       {} as never, // payment
+      {} as never, // companies
     );
 
     const settled = await service.settlePayable(
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 1d0473c7e..01b057a76 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -9,6 +9,16 @@ import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
 import { PaymentService } from "../payment/payment.service";
 import { InitiateResponseDto } from "../payment/payments.dto";
+import { CompaniesService } from "../companies/companies.service";
+
+/** Options forwarded to the payment gateway when settling an invoice. */
+export interface PayInvoiceOptions {
+  method?: string;
+  platform?: "web" | "mobile";
+  payerAccount?: string;
+  returnUrl?: string;
+  failureUrl?: string;
+}
 
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
 const DEFAULT_DUE_DAYS = 14;
@@ -84,6 +94,7 @@ export class BillingService {
     private readonly events: EventEmitter2,
     @Inject(forwardRef(() => PaymentService))
     private readonly payment: PaymentService,
+    private readonly companies: CompaniesService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -104,6 +115,64 @@ export class BillingService {
     return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
   }
 
+  // ── Customer-scoped reads (portal) ───────────────────────────────────────────
+
+  /** Resolve the customer's company id from their IAM user id (null if none). */
+  async resolveCompanyId(userId: string): Promise<string | null> {
+    try {
+      const { company } = await this.companies.getCompanyInfoByUserId(userId);
+      return company?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Every invoice billed to a company, newest first, with billing relations. */
+  findByCompany(companyId: string): Promise<Invoice[]> {
+    return this.invoices.findAll({
+      where: { companyId },
+      relations: { company: true, companyProfile: true },
+      order: { createdAt: "DESC" },
+    });
+  }
+
+  /** Invoices for the signed-in customer; empty when they have no company. */
+  async findForUser(userId: string): Promise<Invoice[]> {
+    const companyId = await this.resolveCompanyId(userId);
+    return companyId ? this.findByCompany(companyId) : [];
+  }
+
+  /** Company-scoped invoice detail (+ lines); 404 when not owned by the user. */
+  async findByIdForUser(
+    id: string,
+    userId: string,
+  ): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const companyId = await this.resolveCompanyId(userId);
+    const invoice = await this.findById(id);
+    if (!companyId || invoice.companyId !== companyId) {
+      throw new NotFoundException(`Invoice ${id} not found`);
+    }
+    return invoice;
+  }
+
+  /**
+   * Initiate gateway payment for one of the customer's own invoices. Verifies
+   * ownership, then charges whichever open invoice the source currently has
+   * (see {@link payInvoice}).
+   */
+  async payInvoiceForUser(
+    id: string,
+    userId: string,
+    opts: PayInvoiceOptions = {},
+  ): Promise<InitiateResponseDto> {
+    const invoice = await this.findByIdForUser(id, userId);
+    return this.payInvoice(
+      invoice.source as Freight.InvoiceSource,
+      invoice.sourceId,
+      opts,
+    );
+  }
+
   // ── Generation ───────────────────────────────────────────────────────────────
 
   /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */
diff --git a/apps/edr-freight-api/src/modules/billing/dto/pay-invoice.dto.ts b/apps/edr-freight-api/src/modules/billing/dto/pay-invoice.dto.ts
new file mode 100644
index 000000000..c29160ab7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/dto/pay-invoice.dto.ts
@@ -0,0 +1,30 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsIn, IsOptional, IsString } from "class-validator";
+
+/** Gateway options for paying an invoice from the customer portal. */
+export class PayInvoiceDto {
+  @ApiPropertyOptional({ description: "Payment method (defaults to TELEBIRR)." })
+  @IsOptional()
+  @IsString()
+  method?: string;
+
+  @ApiPropertyOptional({ enum: ["web", "mobile"], default: "web" })
+  @IsOptional()
+  @IsIn(["web", "mobile"])
+  platform?: "web" | "mobile";
+
+  @ApiPropertyOptional({ description: "Payer account / phone, for wallet methods." })
+  @IsOptional()
+  @IsString()
+  payerAccount?: string;
+
+  @ApiPropertyOptional({ description: "Browser redirect URL on success." })
+  @IsOptional()
+  @IsString()
+  returnUrl?: string;
+
+  @ApiPropertyOptional({ description: "Browser redirect URL on failure." })
+  @IsOptional()
+  @IsString()
+  failureUrl?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/billing/portal-billing.controller.ts b/apps/edr-freight-api/src/modules/billing/portal-billing.controller.ts
new file mode 100644
index 000000000..5a007c320
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/portal-billing.controller.ts
@@ -0,0 +1,60 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+} from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import { CurrentUser } from "@edr/api-common";
+
+import {
+  type AuthUserPayload,
+  resolveAuthUserId,
+} from "../../common/resolve-auth-user-id";
+import { BillingService } from "./billing.service";
+import { PayInvoiceDto } from "./dto/pay-invoice.dto";
+
+/**
+ * Customer-facing billing endpoints. Unlike {@link BillingController} (admin,
+ * org-wide), every route here is force-scoped to the signed-in customer's
+ * company — they only ever see and pay their own invoices.
+ */
+@ApiTags("billing")
+@ApiBearerAuth()
+@Controller("billing")
+export class PortalBillingController {
+  constructor(private readonly billingService: BillingService) {}
+
+  @Get("my-invoices")
+  @ApiOperation({ summary: "List the signed-in customer's invoices" })
+  findMine(@CurrentUser() user: AuthUserPayload) {
+    return this.billingService.findForUser(resolveAuthUserId(user));
+  }
+
+  @Get("my-invoices/:id")
+  @ApiOperation({ summary: "Get one of the customer's invoices (+ line items)" })
+  findMineById(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.billingService.findByIdForUser(id, resolveAuthUserId(user));
+  }
+
+  @Post("my-invoices/:id/pay")
+  @ApiOperation({ summary: "Initiate payment for one of the customer's invoices" })
+  pay(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: AuthUserPayload,
+    @Body() dto: PayInvoiceDto,
+  ) {
+    return this.billingService.payInvoiceForUser(id, resolveAuthUserId(user), {
+      method: dto.method,
+      platform: dto.platform ?? "web",
+      payerAccount: dto.payerAccount,
+      returnUrl: dto.returnUrl,
+      failureUrl: dto.failureUrl,
+    });
+  }
+}

From 6d40d185d6315dc345ec7c43263b188c7a4b8260 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 13:54:14 +0000
Subject: [PATCH 19/63] feat: setup the invoice page in the portal

---
 apps/edr-freight-web/portal/src/App.tsx       |   8 +-
 .../portal/src/constants/URLS.ts              |   6 +
 .../portal/src/constants/apiConfig.ts         |   4 +-
 .../portal/src/lib/currency.ts                |  23 +
 .../portal/src/lib/currentCustomer.ts         |  20 -
 .../src/pages/MyPortalPage/MyPortalPage.tsx   |   4 +-
 .../components/FreightVolumeSection.tsx       |   4 +-
 .../components/InvoicesSection.tsx            |  99 ++--
 .../MyPortalPage/components/StatsSection.tsx  |   2 +-
 .../src/pages/MyPortalPage/constants.ts       |  15 +-
 .../portal/src/pages/MyPortalPage/hooks.ts    |  14 +-
 .../portal/src/pages/billing/BillingPage.tsx  | 382 -------------
 .../src/pages/billing/DeleteInvoiceDialog.tsx |  63 --
 .../src/pages/billing/InvoiceDetailPage.tsx   | 247 ++++++++
 .../portal/src/pages/billing/InvoicesList.tsx | 537 ++++++++++++++++++
 .../src/pages/billing/NewInvoicePage.tsx      | 202 -------
 .../portal/src/pages/billing/invoice-ui.tsx   |  60 ++
 .../portal/src/pages/billing/invoices.mock.ts |  88 ---
 .../portal/src/services/api.ts                |  25 +
 .../portal/src/services/invoices.service.ts   |  89 +++
 20 files changed, 1058 insertions(+), 834 deletions(-)
 create mode 100644 apps/edr-freight-web/portal/src/lib/currency.ts
 delete mode 100644 apps/edr-freight-web/portal/src/lib/currentCustomer.ts
 delete mode 100644 apps/edr-freight-web/portal/src/pages/billing/BillingPage.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/billing/DeleteInvoiceDialog.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/billing/InvoicesList.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/billing/NewInvoicePage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/billing/invoice-ui.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/billing/invoices.mock.ts
 create mode 100644 apps/edr-freight-web/portal/src/services/invoices.service.ts

diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index 8ce1365c5..05c942290 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -31,7 +31,8 @@ import LoginPage from "./pages/accounts/LoginPage";
 import SetPasswordPage from "./pages/accounts/SetPasswordPage";
 import SignupPage from "./pages/accounts/SignupPage";
 import VerificationOtpPage from "./pages/accounts/VerificationOtpPage";
-import BillingPage from "./pages/billing/BillingPage";
+import InvoiceDetailPage from "./pages/billing/InvoiceDetailPage";
+import InvoicesList from "./pages/billing/InvoicesList";
 import BookingContractPage from "./pages/bookings/BookingContractPage";
 import BookingDetailPage from "./pages/bookings/BookingDetailPage";
 import EditBookingPage from "./pages/bookings/EditBookingPage";
@@ -188,7 +189,7 @@ const sidebarItems: SidebarItem[] = [
     icon: <MapPin size={18} />,
   },
   {
-    label: "Billing",
+    label: "Invoices",
     href: "/billing",
     icon: <Receipt size={18} />,
   },
@@ -285,7 +286,8 @@ const App = () => {
             />
             <Route path="/contracts/:id" element={<ContractDetailPage />} />
             <Route path="/tracking" element={<TrackingPage />} />
-            <Route path="/billing" element={<BillingPage />} />
+            <Route path="/billing" element={<InvoicesList />} />
+            <Route path="/billing/:id" element={<InvoiceDetailPage />} />
             {/* Profile was merged into Settings — keep old links working. */}
             <Route
               path="/profile"
diff --git a/apps/edr-freight-web/portal/src/constants/URLS.ts b/apps/edr-freight-web/portal/src/constants/URLS.ts
index 57d25dc55..22f2a441b 100644
--- a/apps/edr-freight-web/portal/src/constants/URLS.ts
+++ b/apps/edr-freight-web/portal/src/constants/URLS.ts
@@ -143,4 +143,10 @@ export const URL_CONSTANTS = {
     INTENT: (bookingId: string) => `/api/payments/intents/${bookingId}`,
     CHECKOUT: "/api/payments/checkout",
   },
+
+  BILLING: {
+    MY_INVOICES: "/api/billing/my-invoices",
+    MY_INVOICE_BY_ID: (id: string) => `/api/billing/my-invoices/${id}`,
+    PAY_INVOICE: (id: string) => `/api/billing/my-invoices/${id}/pay`,
+  },
 };
diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index 1b070d87d..a24cb4a6d 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,5 @@
-export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-// export const API_BASE_URL = 'http://localhost:3001';
+// export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/portal/src/lib/currency.ts b/apps/edr-freight-web/portal/src/lib/currency.ts
new file mode 100644
index 000000000..d41b4edda
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/lib/currency.ts
@@ -0,0 +1,23 @@
+/** Currency code carried on invoices / dashboard figures (ETB, USD, DJF, …). */
+export type Currency = string;
+
+const SYMBOLS: Record<string, string> = {
+  USD: "$",
+  ETB: "Br",
+  DJF: "DJF",
+};
+
+/**
+ * Format a money amount with its currency symbol, e.g. `Br 12,500.00`.
+ * Unknown currency codes fall back to printing the raw code.
+ */
+export function formatCurrency(
+  amount: number,
+  currency: Currency = "ETB",
+): string {
+  const symbol = SYMBOLS[currency] ?? currency;
+  return `${symbol} ${Number(amount ?? 0).toLocaleString(undefined, {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })}`;
+}
diff --git a/apps/edr-freight-web/portal/src/lib/currentCustomer.ts b/apps/edr-freight-web/portal/src/lib/currentCustomer.ts
deleted file mode 100644
index 47fc1efa6..000000000
--- a/apps/edr-freight-web/portal/src/lib/currentCustomer.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { invoices, type Invoice } from "@/pages/billing/invoices.mock";
-import { customers, type Customer } from "@/pages/customers/customers.mock";
-
-/**
- * Mock "logged-in customer". When auth integrates, replace this with the value
- * pulled from `@edr/iamui-common` / the JWT context.
- */
-const CURRENT_CUSTOMER_ID = 1;
-
-export function getCurrentCustomer(): Customer {
-  return (
-    customers.find((c) => c.id === CURRENT_CUSTOMER_ID) ??
-    (customers[0] as Customer)
-  );
-}
-
-export function getMyInvoices(): Invoice[] {
-  const me = getCurrentCustomer();
-  return invoices.filter((inv) => inv.customerId === me.id);
-}
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
index cb350916d..fccc4d98f 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
@@ -1,5 +1,5 @@
-import type { Currency } from "@/pages/billing/invoices.mock";
-import { formatCurrency } from "@/pages/billing/invoices.mock";
+import type { Currency } from "@/lib/currency";
+import { formatCurrency } from "@/lib/currency";
 import { Group, Grid, Select, Stack } from "@mantine/core";
 import { useState } from "react";
 import { useNavigate } from "react-router-dom";
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/FreightVolumeSection.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/FreightVolumeSection.tsx
index 27b74cb6f..c84f94c35 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/FreightVolumeSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/FreightVolumeSection.tsx
@@ -1,7 +1,7 @@
 import { Box, Group, Skeleton, Text } from "@mantine/core";
 import { memo } from "react";
-import type { Currency } from "@/pages/billing/invoices.mock";
-import { formatCurrency } from "@/pages/billing/invoices.mock";
+import type { Currency } from "@/lib/currency";
+import { formatCurrency } from "@/lib/currency";
 import { formatPct } from "../constants";
 import { Card } from "./Card";
 
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
index 3ebb9606f..22362c816 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
@@ -1,7 +1,7 @@
-import type { Currency, InvoiceStatus } from "@/pages/billing/invoices.mock";
-import { formatCurrency } from "@/pages/billing/invoices.mock";
+import { formatCurrency } from "@/lib/currency";
+import type { PortalInvoice } from "@/services/invoices.service";
 import { Box, Group, Stack, Text } from "@mantine/core";
-import { format } from "date-fns";
+import { Freight } from "@edr/types";
 import { CheckCircle2, ChevronRight, Clock3, Zap } from "lucide-react";
 import { memo } from "react";
 import { Link } from "react-router-dom";
@@ -10,26 +10,22 @@ import { Card } from "./Card";
 import { EmptyState } from "./EmptyState";
 
 interface InvoicesSectionProps {
-  invoices: Array<{
-    id: number;
-    number: string;
-    bookingReference: string;
-    amount: number;
-    currency: Currency;
-    status: InvoiceStatus;
-    dueDate: string;
-    paidDate: string | null;
-  }>;
+  invoices: PortalInvoice[];
 }
 
+const titleCase = (v: string) =>
+  v ? v.charAt(0).toUpperCase() + v.slice(1).toLowerCase() : "";
+
 export const InvoicesSection = memo(function InvoicesSection({
   invoices,
 }: InvoicesSectionProps) {
   const outstandingInvoices = invoices.filter(
-    (inv) => inv.status === "Sent" || inv.status === "Overdue",
+    (inv) =>
+      inv.status === Freight.InvoiceStatus.Pending ||
+      inv.status === Freight.InvoiceStatus.Overdue,
   );
   const totalOutstanding = outstandingInvoices.reduce(
-    (sum, inv) => sum + inv.amount,
+    (sum, inv) => sum + Number(inv.totalAmount),
     0,
   );
 
@@ -56,14 +52,9 @@ export const InvoicesSection = memo(function InvoicesSection({
         <Text fz={24} fw={800} mt={4} c="edr-text">
           {formatCurrency(totalOutstanding || 0, "ETB")}
         </Text>
-        <Group
-          justify="space-between"
-          align="center"
-          mt={8}
-          wrap="nowrap"
-        >
+        <Group justify="space-between" align="center" mt={8} wrap="nowrap">
           <Text fz={12} c="edr-amber-text">
-            {outstandingInvoices.length || 2} invoices unpaid
+            {outstandingInvoices.length} invoices unpaid
           </Text>
           <Group
             gap={5}
@@ -87,61 +78,55 @@ export const InvoicesSection = memo(function InvoicesSection({
         <Stack gap={0}>
           {invoices.map((invoice, i) => {
             const badge = INVOICE_BADGE[invoice.status];
-            const dueText =
-              invoice.status === "Paid"
-                ? `Paid ${format(new Date(invoice.paidDate ?? invoice.dueDate), "MMM d")}`
-                : invoice.status === "Overdue"
-                  ? "Overdue 3 days"
-                  : `Due ${invoice.dueDate}`;
-            const DueIcon =
-              invoice.status === "Paid" ? CheckCircle2 : Clock3;
-            const dueIconColor =
-              invoice.status === "Paid"
-                ? cv("edr-green.5")
-                : cv("edr-muted");
+            const isPaid = invoice.status === Freight.InvoiceStatus.Paid;
+            const isOverdue = invoice.status === Freight.InvoiceStatus.Overdue;
+            const dueText = isPaid
+              ? "Paid"
+              : isOverdue
+                ? "Overdue"
+                : `Due ${new Date(invoice.dueAt).toLocaleDateString()}`;
+            const DueIcon = isPaid ? CheckCircle2 : Clock3;
+            const dueIconColor = isPaid ? cv("edr-green.5") : cv("edr-muted");
 
             return (
               <Box key={invoice.id}>
                 {i > 0 && <Box h={1} bg="edr-divider" />}
                 <Stack gap={8} py={10}>
-                  <Group
-                    justify="space-between"
-                    align="flex-start"
-                    wrap="nowrap"
-                  >
+                  <Group justify="space-between" align="flex-start" wrap="nowrap">
                     <Box>
                       <Text fz={13} fw={700} c="edr-text">
-                        {invoice.number}
+                        {invoice.invoiceNumber}
                       </Text>
                       <Text fz={11} c="edr-muted">
-                        {invoice.bookingReference}
+                        {titleCase(invoice.source)} · {titleCase(invoice.type)}
                       </Text>
                     </Box>
                     <Text fz={14} fw={700} c="edr-text">
-                      {formatCurrency(invoice.amount, invoice.currency)}
+                      {formatCurrency(
+                        Number(invoice.totalAmount),
+                        invoice.currency,
+                      )}
                     </Text>
                   </Group>
-                  <Group
-                    justify="space-between"
-                    align="center"
-                    wrap="nowrap"
-                  >
+                  <Group justify="space-between" align="center" wrap="nowrap">
                     <Group gap={5} align="center">
                       <DueIcon size={13} color={dueIconColor} />
                       <Text fz={12} c="edr-muted">
                         {dueText}
                       </Text>
                     </Group>
-                    <Box
-                      bg={badge.bg}
-                      px={10}
-                      py={4}
-                      className="rounded-full"
-                    >
-                      <Text fz={11} fw={700} c={badge.text}>
-                        {badge.label}
-                      </Text>
-                    </Box>
+                    {badge && (
+                      <Box
+                        bg={badge.bg}
+                        px={10}
+                        py={4}
+                        className="rounded-full"
+                      >
+                        <Text fz={11} fw={700} c={badge.text}>
+                          {badge.label}
+                        </Text>
+                      </Box>
+                    )}
                   </Group>
                 </Stack>
               </Box>
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/StatsSection.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/StatsSection.tsx
index dae90842b..3ddd9be4d 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/StatsSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/StatsSection.tsx
@@ -1,4 +1,4 @@
-import { formatCurrency } from "@/pages/billing/invoices.mock";
+import { formatCurrency } from "@/lib/currency";
 import { SimpleGrid } from "@mantine/core";
 import { CheckCircle2, Clock3, Layers, Truck, Wallet } from "lucide-react";
 import { memo } from "react";
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts b/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
index 70e58f77c..ea5567ab8 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
@@ -12,7 +12,7 @@ import {
   Wallet,
   type LucideIcon,
 } from "lucide-react";
-import type { InvoiceStatus } from "@/pages/billing/invoices.mock";
+import { Freight } from "@edr/types";
 
 export const cv = (token: string) => {
   const [name, shade] = token.split(".");
@@ -514,12 +514,13 @@ export const ACTION_PROPS: Record<
 };
 
 export const INVOICE_BADGE: Record<
-  InvoiceStatus,
+  Freight.InvoiceStatus,
   { label: string; bg: string; text: string }
 > = {
-  Draft: { label: "Draft", bg: "edr-slate-soft", text: "edr-slate" },
-  Sent: { label: "Due soon", bg: "edr-amber-soft", text: "edr-amber-text" },
-  Paid: { label: "Paid", bg: "edr-soft", text: "edr-green.7" },
-  Overdue: { label: "Overdue", bg: "edr-red-soft", text: "edr-red" },
-  Cancelled: { label: "Cancelled", bg: "edr-slate-soft", text: "edr-slate" },
+  [Freight.InvoiceStatus.Draft]: { label: "Draft", bg: "edr-slate-soft", text: "edr-slate" },
+  [Freight.InvoiceStatus.Pending]: { label: "Due soon", bg: "edr-amber-soft", text: "edr-amber-text" },
+  [Freight.InvoiceStatus.Paid]: { label: "Paid", bg: "edr-soft", text: "edr-green.7" },
+  [Freight.InvoiceStatus.Overdue]: { label: "Overdue", bg: "edr-red-soft", text: "edr-red" },
+  [Freight.InvoiceStatus.Cancelled]: { label: "Cancelled", bg: "edr-slate-soft", text: "edr-slate" },
+  [Freight.InvoiceStatus.Refunded]: { label: "Refunded", bg: "edr-blue-soft", text: "edr-blue" },
 };
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/hooks.ts b/apps/edr-freight-web/portal/src/pages/MyPortalPage/hooks.ts
index 8c1bb6b04..08a3ec97e 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/hooks.ts
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/hooks.ts
@@ -1,13 +1,14 @@
 import { useQuery } from "@tanstack/react-query";
-import { useMemo } from "react";
+import { Freight } from "@edr/types";
 import useAuth from "@/hooks/useAuth";
-import { getMyInvoices } from "@/lib/currentCustomer";
 import { api } from "@/services/api";
 import { ACTIVE_STATUSES } from "./constants";
 
 export function useMyPortalData(selectedProfileId?: string) {
   const { user, customer, company } = useAuth();
-  const myInvoices = useMemo(() => getMyInvoices(), []);
+
+  const invoicesQuery = useQuery(api.invoices.listMy.queryOptions());
+  const myInvoices = invoicesQuery.data ?? [];
 
   const companyProfiles = company?.company?.companyProfiles ?? [];
 
@@ -59,11 +60,13 @@ export function useMyPortalData(selectedProfileId?: string) {
   ).length;
 
   const outstandingInvoices = myInvoices.filter(
-    (inv) => inv.status === "Sent" || inv.status === "Overdue",
+    (inv) =>
+      inv.status === Freight.InvoiceStatus.Pending ||
+      inv.status === Freight.InvoiceStatus.Overdue,
   );
 
   const totalOutstanding = outstandingInvoices.reduce(
-    (sum, inv) => sum + inv.amount,
+    (sum, inv) => sum + Number(inv.totalAmount),
     0,
   );
 
@@ -91,6 +94,7 @@ export function useMyPortalData(selectedProfileId?: string) {
     bookingsQuery,
     dashboardQuery,
     contractsQuery,
+    invoicesQuery,
     allContracts,
     recentContracts,
     activeContractsCount,
diff --git a/apps/edr-freight-web/portal/src/pages/billing/BillingPage.tsx b/apps/edr-freight-web/portal/src/pages/billing/BillingPage.tsx
deleted file mode 100644
index 8b7ac4557..000000000
--- a/apps/edr-freight-web/portal/src/pages/billing/BillingPage.tsx
+++ /dev/null
@@ -1,382 +0,0 @@
-import { useMemo, useState } from "react";
-import {
-  AlertCircle,
-  Clock,
-  DollarSign,
-  Download,
-  Filter,
-  MoreHorizontal,
-  Pencil,
-  Plus,
-  Receipt,
-  Search,
-  Trash2,
-} from "lucide-react";
-
-import Breadcrumbs from "@/components/Breadcrumbs";
-import NewInvoicePage from "./NewInvoicePage";
-import DeleteInvoiceDialog from "./DeleteInvoiceDialog";
-import { formatCurrency, invoices, type InvoiceStatus } from "./invoices.mock";
-import {
-  DataTable,
-  DataTableFooter,
-  type ColumnDef,
-  usePagination,
-  Button,
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-  Input,
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-} from "@edr/ui-common";
-
-type FilterValue = "All" | InvoiceStatus;
-
-const FILTERS: FilterValue[] = [
-  "All",
-  "Draft",
-  "Sent",
-  "Paid",
-  "Overdue",
-  "Cancelled",
-];
-
-export default function BillingPage() {
-  const { pagination, setPagination } = usePagination({ pageSize: 10 });
-  const [filter, setFilter] = useState<FilterValue>("All");
-  const [query, setQuery] = useState("");
-
-  const filtered = useMemo(() => {
-    const q = query.trim().toLowerCase();
-    return invoices.filter((inv) => {
-      if (filter !== "All" && inv.status !== filter) return false;
-      if (!q) return true;
-      return (
-        inv.number.toLowerCase().includes(q) ||
-        inv.customer.toLowerCase().includes(q) ||
-        inv.bookingReference.toLowerCase().includes(q)
-      );
-    });
-  }, [filter, query]);
-
-  const total = filtered.length;
-  const pageCount = Math.ceil(total / pagination.pageSize);
-  const start = pagination.pageIndex * pagination.pageSize;
-  const end = Math.min(start + pagination.pageSize, total);
-
-  const paginatedData = useMemo(
-    () => filtered.slice(start, end),
-    [start, end, filtered],
-  );
-
-  const totalRevenue = invoices
-    .filter((inv) => inv.status === "Paid" && inv.currency === "USD")
-    .reduce((sum, inv) => sum + inv.amount, 0);
-  const outstanding = invoices
-    .filter(
-      (inv) =>
-        (inv.status === "Sent" || inv.status === "Overdue") &&
-        inv.currency === "USD",
-    )
-    .reduce((sum, inv) => sum + inv.amount, 0);
-  const overdueCount = invoices.filter(
-    (inv) => inv.status === "Overdue",
-  ).length;
-
-  const columns: ColumnDef<(typeof invoices)[number]>[] = [
-    {
-      id: "invoice",
-      header: "Invoice",
-      cell: ({ row }) => {
-        const inv = row.original;
-        return (
-          <div className="flex items-center gap-3">
-            <div className="flex h-10 w-10 items-center justify-center rounded-full bg-primary text-primary-foreground">
-              <Receipt />
-            </div>
-            <div>
-              <p className="font-medium text-slate-900">{inv.number}</p>
-              <p className="text-sm text-slate-500">Issued {inv.issueDate}</p>
-            </div>
-          </div>
-        );
-      },
-    },
-    {
-      accessorKey: "customer",
-      header: "Customer",
-    },
-    {
-      accessorKey: "bookingReference",
-      header: "Booking",
-    },
-    {
-      id: "amount",
-      header: "Amount",
-      cell: ({ row }) => {
-        const inv = row.original;
-        return (
-          <span className="text-sm font-medium text-slate-900">
-            {formatCurrency(inv.amount, inv.currency)}
-          </span>
-        );
-      },
-    },
-    {
-      accessorKey: "dueDate",
-      header: "Due Date",
-    },
-    {
-      accessorKey: "status",
-      header: "Status",
-      cell: ({ row }) => <StatusBadge status={row.original.status} />,
-    },
-    {
-      id: "actions",
-      size: 40,
-      cell: ({ row }) => {
-        const invoice = row.original;
-        return (
-          <div
-            className="flex justify-end"
-            onClick={(e) => e.stopPropagation()}
-          >
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="icon">
-                  <MoreHorizontal />
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end">
-                <DropdownMenuItem>
-                  <Download />
-                  Download
-                </DropdownMenuItem>
-                <NewInvoicePage
-                  mode="edit"
-                  invoice={{
-                    number: invoice.number,
-                    customerId: invoice.customerId,
-                    bookingReference: invoice.bookingReference,
-                    amount: invoice.amount,
-                    currency: invoice.currency,
-                    status: invoice.status,
-                    issueDate: invoice.issueDate,
-                    dueDate: invoice.dueDate,
-                    notes: invoice.notes,
-                  }}
-                >
-                  <DropdownMenuItem onSelect={(e: Event) => e.preventDefault()}>
-                    <Pencil />
-                    Edit
-                  </DropdownMenuItem>
-                </NewInvoicePage>
-                <DropdownMenuSeparator />
-                <DeleteInvoiceDialog invoiceNumber={invoice.number}>
-                  <DropdownMenuItem
-                    onSelect={(e: Event) => e.preventDefault()}
-                    variant="destructive"
-                  >
-                    <Trash2 />
-                    Void
-                  </DropdownMenuItem>
-                </DeleteInvoiceDialog>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          </div>
-        );
-      },
-    },
-  ];
-
-  return (
-    <div className="min-h-screen p-6">
-      <div className="space-y-6">
-        <Breadcrumbs items={[{ label: "Billing" }]} />
-
-        <Card className="p-6 flex-row justify-between">
-          <div>
-            <h1 className="text-3xl font-bold tracking-tight text-slate-900">
-              Billing
-            </h1>
-            <p className="mt-1 text-sm text-secondary-foreground">
-              Manage invoices, payments, and financial records.
-            </p>
-          </div>
-
-          <div className="flex flex-col items-stretch gap-3 sm:flex-row sm:items-center">
-            <div className="relative w-full sm:w-80">
-              <Search className="pointer-events-none absolute left-2 top-1/2 h-4 w-4 -translate-y-1/2 text-slate-400" />
-              <Input
-                type="search"
-                value={query}
-                onChange={(e) => {
-                  setQuery(e.target.value);
-                  setPagination({
-                    pageIndex: 0,
-                    pageSize: pagination.pageSize,
-                  });
-                }}
-                placeholder="Search invoices..."
-                className="pl-8!"
-              />
-            </div>
-
-            <NewInvoicePage>
-              <Button>
-                <Plus />
-                New Invoice
-              </Button>
-            </NewInvoicePage>
-          </div>
-        </Card>
-
-        <div className="grid gap-4 md:grid-cols-3">
-          <Card>
-            <CardContent className="flex items-center justify-between">
-              <div>
-                <p className="text-sm text-slate-500">Total Revenue (USD)</p>
-                <h3 className="mt-2 text-3xl font-bold text-slate-900">
-                  {formatCurrency(totalRevenue, "USD")}
-                </h3>
-              </div>
-              <div className="flex h-12 w-12 items-center justify-center rounded-2xl bg-primary/10 text-primary">
-                <DollarSign />
-              </div>
-            </CardContent>
-          </Card>
-
-          <Card>
-            <CardContent className="flex items-center justify-between">
-              <div>
-                <p className="text-sm text-slate-500">Outstanding (USD)</p>
-                <h3 className="mt-2 text-3xl font-bold text-slate-900">
-                  {formatCurrency(outstanding, "USD")}
-                </h3>
-              </div>
-              <div className="flex h-12 w-12 items-center justify-center rounded-2xl bg-primary/10 text-primary">
-                <Clock />
-              </div>
-            </CardContent>
-          </Card>
-
-          <Card>
-            <CardContent className="flex items-center justify-between">
-              <div>
-                <p className="text-sm text-slate-500">Overdue Invoices</p>
-                <h3 className="mt-2 text-3xl font-bold text-slate-900">
-                  {overdueCount}
-                </h3>
-              </div>
-              <div className="flex h-12 w-12 items-center justify-center rounded-2xl bg-red-100 text-red-600">
-                <AlertCircle />
-              </div>
-            </CardContent>
-          </Card>
-        </div>
-
-        <Card className="p-2">
-          <div className="flex flex-wrap gap-1">
-            {FILTERS.map((f) => {
-              const isActive = f === filter;
-              const count =
-                f === "All"
-                  ? invoices.length
-                  : invoices.filter((inv) => inv.status === f).length;
-              return (
-                <button
-                  key={f}
-                  type="button"
-                  onClick={() => {
-                    setFilter(f);
-                    setPagination({
-                      pageIndex: 0,
-                      pageSize: pagination.pageSize,
-                    });
-                  }}
-                  className={
-                    isActive
-                      ? "inline-flex items-center gap-2 rounded-2xl bg-primary px-4 py-2 text-sm font-medium text-primary-foreground"
-                      : "inline-flex items-center gap-2 rounded-2xl px-4 py-2 text-sm font-medium text-slate-600 transition hover:bg-primary/10 hover:text-primary"
-                  }
-                >
-                  {f}
-                  <span
-                    className={
-                      isActive
-                        ? "rounded-full bg-white/20 px-2 py-0.5 text-xs"
-                        : "rounded-full bg-slate-100 px-2 py-0.5 text-xs text-slate-600"
-                    }
-                  >
-                    {count}
-                  </span>
-                </button>
-              );
-            })}
-          </div>
-        </Card>
-
-        <Card className="gap-0">
-          <CardHeader className="flex flex-row items-center justify-between border-b">
-            <div>
-              <CardTitle>Invoices</CardTitle>
-              <CardDescription>
-                Issued invoices and their payment status.
-              </CardDescription>
-            </div>
-
-            <Button variant="secondary" size="sm">
-              <Filter />
-              Filter
-            </Button>
-          </CardHeader>
-
-          <CardContent className="px-0">
-            <DataTable
-              columns={columns}
-              data={paginatedData}
-              status="success"
-              onRowClick={() => { }}
-              pagination={{
-                pageIndex: pagination.pageIndex,
-                pageSize: pagination.pageSize,
-                pageCount: pageCount,
-                totalCount: total,
-              }}
-              tableOptions={{
-                state: { pagination },
-                onPaginationChange: setPagination,
-              }}
-              containerClassName="border-b shadow-none"
-              footer={DataTableFooter}
-            />
-          </CardContent>
-        </Card>
-      </div>
-    </div>
-  );
-}
-
-function StatusBadge({ status }: { status: InvoiceStatus }) {
-  const styles: Record<InvoiceStatus, string> = {
-    Draft: "bg-slate-100 text-slate-600",
-    Sent: "bg-sky-100 text-sky-700",
-    Paid: "bg-emerald-100 text-emerald-700",
-    Overdue: "bg-red-100 text-red-700",
-    Cancelled: "bg-amber-100 text-amber-700",
-  };
-
-  return (
-    <span
-      className={`inline-flex rounded-full px-3 py-1 text-xs font-medium ${styles[status]}`}
-    >
-      {status}
-    </span>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/DeleteInvoiceDialog.tsx b/apps/edr-freight-web/portal/src/pages/billing/DeleteInvoiceDialog.tsx
deleted file mode 100644
index a4e278cb1..000000000
--- a/apps/edr-freight-web/portal/src/pages/billing/DeleteInvoiceDialog.tsx
+++ /dev/null
@@ -1,63 +0,0 @@
-import type { ReactNode } from "react";
-
-import {
-  Dialog,
-  DialogClose,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle,
-  DialogTrigger,
-} from "@/components/ui/dialog";
-
-import { Button } from "@/components/ui/button";
-
-export interface DeleteInvoiceDialogProps {
-  invoiceNumber: string;
-  onConfirm?: () => void;
-  children: ReactNode;
-}
-
-export default function DeleteInvoiceDialog({
-  invoiceNumber,
-  onConfirm,
-  children,
-}: DeleteInvoiceDialogProps) {
-  return (
-    <Dialog>
-      <DialogTrigger asChild>{children}</DialogTrigger>
-
-      <DialogContent className="sm:max-w-md rounded-3xl">
-        <DialogHeader>
-          <DialogTitle className="text-xl font-bold">
-            Void invoice?
-          </DialogTitle>
-
-          <DialogDescription>
-            This will void invoice{" "}
-            <span className="font-semibold text-slate-900">
-              {invoiceNumber}
-            </span>
-            . This action cannot be undone.
-          </DialogDescription>
-        </DialogHeader>
-
-        <DialogFooter className="mt-2">
-          <DialogClose asChild>
-            <Button variant="outline">Cancel</Button>
-          </DialogClose>
-
-          <DialogClose asChild>
-            <Button
-              onClick={onConfirm}
-              className="bg-red-600 text-white hover:bg-red-700"
-            >
-              Void Invoice
-            </Button>
-          </DialogClose>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
new file mode 100644
index 000000000..510c7aad7
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
@@ -0,0 +1,247 @@
+import { useNavigate, useParams } from "react-router-dom";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  Alert,
+  Box,
+  Button,
+  Center,
+  Divider,
+  Group,
+  Loader,
+  Paper,
+  SimpleGrid,
+  Stack,
+  Table,
+  Text,
+  Title,
+} from "@mantine/core";
+import { ArrowLeft, CreditCard, Info } from "lucide-react";
+
+import { api } from "@/services/api";
+import { formatCurrency } from "@/lib/currency";
+import { BORDER, INK, MUTED } from "../contracts/contract-ui";
+import {
+  billedTo,
+  fmtDate,
+  InvoiceStatusBadge,
+  isPayable,
+  titleCase,
+} from "./invoice-ui";
+
+function MetaItem({ label, value }: { label: string; value: string }) {
+  return (
+    <Box>
+      <Text fz={11} fw={700} c={MUTED} style={{ textTransform: "uppercase", letterSpacing: "0.05em" }}>
+        {label}
+      </Text>
+      <Text fz={14} mt={4} style={{ color: INK }}>
+        {value}
+      </Text>
+    </Box>
+  );
+}
+
+export default function InvoiceDetailPage() {
+  const { id = "" } = useParams();
+  const navigate = useNavigate();
+
+  const { data: invoice, isLoading, isError } = useQuery(
+    api.invoices.get.queryOptions({ input: { id } }),
+  );
+
+  const payMutation = useMutation(
+    api.invoices.pay.mutationOptions({
+      onSuccess: (res) => {
+        const url = res.clientAction?.url;
+        if (url) window.location.href = url;
+      },
+    }),
+  );
+
+  if (isLoading) {
+    return (
+      <Center py={80}>
+        <Loader color="edr-green" />
+      </Center>
+    );
+  }
+
+  if (isError || !invoice) {
+    return (
+      <Box style={{ padding: "28px 32px" }}>
+        <Button
+          variant="subtle"
+          color="gray"
+          leftSection={<ArrowLeft size={16} />}
+          onClick={() => navigate("/billing")}
+          mb="md"
+        >
+          Back to invoices
+        </Button>
+        <Alert color="red" title="Invoice not found">
+          We couldn't load this invoice. It may not exist or you may not have
+          access to it.
+        </Alert>
+      </Box>
+    );
+  }
+
+  const payable = isPayable(invoice.status);
+  const lines = invoice.lines ?? [];
+
+  const handlePay = () => {
+    const returnUrl = `${window.location.origin}/payment/success`;
+    const failureUrl = `${window.location.origin}/payment/failure`;
+    payMutation.mutate({ id, payload: { returnUrl, failureUrl } });
+  };
+
+  return (
+    <Box style={{ padding: "28px 32px 32px" }}>
+      <Stack gap="lg">
+        <Button
+          variant="subtle"
+          color="gray"
+          leftSection={<ArrowLeft size={16} />}
+          onClick={() => navigate("/billing")}
+          style={{ alignSelf: "flex-start" }}
+          styles={{ root: { fontWeight: 600 } }}
+        >
+          Back to invoices
+        </Button>
+
+        {/* Header */}
+        <Group justify="space-between" align="flex-start" wrap="wrap" gap="md">
+          <Group gap={12} align="center" wrap="wrap">
+            <Title order={1} fw={800} fz={26} style={{ letterSpacing: "-0.01em" }}>
+              {invoice.invoiceNumber}
+            </Title>
+            <InvoiceStatusBadge status={invoice.status} />
+          </Group>
+          {payable && (
+            <Button
+              color="edr-green"
+              radius="md"
+              size="md"
+              leftSection={<CreditCard size={16} />}
+              loading={payMutation.isPending}
+              onClick={handlePay}
+              styles={{ root: { fontWeight: 600, height: 42, paddingInline: 18 } }}
+            >
+              Pay {formatCurrency(Number(invoice.totalAmount), invoice.currency)}
+            </Button>
+          )}
+        </Group>
+
+        {payMutation.isError && (
+          <Alert color="red" icon={<Info size={16} />} title="Payment could not be started">
+            Please try again, or contact support if the problem persists.
+          </Alert>
+        )}
+
+        {/* Summary */}
+        <Paper withBorder radius="lg" p="lg" style={{ borderColor: BORDER }}>
+          <SimpleGrid cols={{ base: 1, sm: 2, md: 4 }} spacing="lg">
+            <MetaItem label="Billed To" value={billedTo(invoice)} />
+            <MetaItem label="Source" value={`${titleCase(invoice.source)} · ${invoice.type}`} />
+            <MetaItem label="Issued" value={fmtDate(invoice.issuedAt)} />
+            <MetaItem label="Due" value={fmtDate(invoice.dueAt)} />
+          </SimpleGrid>
+
+          <Divider my="lg" color={BORDER} />
+
+          <Group justify="space-between" align="center">
+            <Text fz={14} fw={700} c={MUTED} style={{ textTransform: "uppercase", letterSpacing: "0.05em" }}>
+              Total
+            </Text>
+            <Text fz={24} fw={800} style={{ color: INK }}>
+              {formatCurrency(Number(invoice.totalAmount), invoice.currency)}
+            </Text>
+          </Group>
+        </Paper>
+
+        {/* Line items */}
+        <Paper
+          withBorder
+          radius="lg"
+          style={{ borderColor: BORDER, overflow: "hidden" }}
+        >
+          <Box px="lg" py="md" style={{ borderBottom: `1px solid ${BORDER}` }}>
+            <Text fz={15} fw={700} style={{ color: INK }}>
+              Line items
+            </Text>
+          </Box>
+          <Box style={{ overflowX: "auto" }}>
+            <Table
+              verticalSpacing={12}
+              horizontalSpacing={20}
+              styles={{
+                th: {
+                  fontSize: 11,
+                  fontWeight: 700,
+                  letterSpacing: "0.05em",
+                  textTransform: "uppercase",
+                  color: MUTED,
+                  background: "#F8FAFC",
+                  borderBottom: `1px solid ${BORDER}`,
+                  whiteSpace: "nowrap",
+                },
+                td: { borderBottom: `1px solid ${BORDER}` },
+              }}
+            >
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th>Charge</Table.Th>
+                  <Table.Th ta="right">Qty</Table.Th>
+                  <Table.Th ta="right">Unit Rate</Table.Th>
+                  <Table.Th ta="right">Amount</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {lines.length === 0 && (
+                  <Table.Tr>
+                    <Table.Td colSpan={4}>
+                      <Center py={28}>
+                        <Text fz={13} c="dimmed">
+                          No line items on this invoice.
+                        </Text>
+                      </Center>
+                    </Table.Td>
+                  </Table.Tr>
+                )}
+                {lines.map((line) => (
+                  <Table.Tr key={line.id}>
+                    <Table.Td>
+                      <Text fz={14} fw={600} style={{ color: INK }}>
+                        {titleCase(line.chargeType)}
+                      </Text>
+                      {line.description && (
+                        <Text fz={12} c="dimmed">
+                          {line.description}
+                        </Text>
+                      )}
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text fz={13} style={{ color: INK }}>
+                        {Number(line.quantity)}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text fz={13} style={{ color: INK }}>
+                        {formatCurrency(Number(line.unitRate), line.currency)}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text fz={13} fw={700} style={{ color: INK }}>
+                        {formatCurrency(Number(line.amount), line.currency)}
+                      </Text>
+                    </Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Box>
+        </Paper>
+      </Stack>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/InvoicesList.tsx b/apps/edr-freight-web/portal/src/pages/billing/InvoicesList.tsx
new file mode 100644
index 000000000..e1d45857f
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/billing/InvoicesList.tsx
@@ -0,0 +1,537 @@
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Box,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Paper,
+  Select,
+  Stack,
+  Table,
+  Text,
+  TextInput,
+  Title,
+} from "@mantine/core";
+import {
+  AlertTriangle,
+  ChevronLeft,
+  ChevronRight,
+  CreditCard,
+  Eye,
+  FileStack,
+  Inbox,
+  Receipt,
+  Search,
+  Wallet,
+  X,
+} from "lucide-react";
+import { Freight } from "@edr/types";
+
+import { api } from "@/services/api";
+import { formatCurrency } from "@/lib/currency";
+import {
+  BORDER,
+  GREEN,
+  INK,
+  MUTED,
+  StatCard,
+} from "../contracts/contract-ui";
+import {
+  billedTo,
+  fmtDate,
+  InvoiceStatusBadge,
+  isPayable,
+  PAYABLE_STATUSES,
+  titleCase,
+} from "./invoice-ui";
+
+const PAGE_SIZES = ["10", "25", "50"];
+
+export default function InvoicesList() {
+  const navigate = useNavigate();
+  const [query, setQuery] = useState("");
+  const [statusFilter, setStatusFilter] = useState<string | null>(null);
+  const [pageIndex, setPageIndex] = useState(0);
+  const [pageSize, setPageSize] = useState(10);
+
+  const { data, isLoading, isError } = useQuery(
+    api.invoices.listMy.queryOptions(),
+  );
+
+  const all = useMemo(() => data ?? [], [data]);
+
+  const stats = useMemo(() => {
+    const outstanding = all.filter((i) =>
+      PAYABLE_STATUSES.includes(i.status),
+    ).length;
+    const overdue = all.filter(
+      (i) => i.status === Freight.InvoiceStatus.Overdue,
+    ).length;
+    return { outstanding, overdue, total: all.length };
+  }, [all]);
+
+  const rows = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return all.filter((inv) => {
+      if (statusFilter && inv.status !== statusFilter) return false;
+      if (!q) return true;
+      return (
+        inv.invoiceNumber.toLowerCase().includes(q) ||
+        inv.source.toLowerCase().includes(q) ||
+        inv.sourceId.toLowerCase().includes(q) ||
+        billedTo(inv).toLowerCase().includes(q)
+      );
+    });
+  }, [all, query, statusFilter]);
+
+  const total = rows.length;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const clampedIndex = Math.min(pageIndex, pageCount - 1);
+  const start = total === 0 ? 0 : clampedIndex * pageSize + 1;
+  const end = Math.min((clampedIndex + 1) * pageSize, total);
+  const pageRows = rows.slice(clampedIndex * pageSize, clampedIndex * pageSize + pageSize);
+
+  const resetPage = () => setPageIndex(0);
+  const goToPage = (i: number) =>
+    setPageIndex(Math.max(0, Math.min(i, pageCount - 1)));
+
+  const hasFilters = !!query || !!statusFilter;
+
+  return (
+    <Box style={{ padding: "28px 32px 32px" }}>
+      <Stack gap="lg">
+        {/* Header */}
+        <Group justify="space-between" align="center" wrap="wrap" gap="md">
+          <Title order={1} fw={800} fz={26} style={{ letterSpacing: "-0.01em" }}>
+            Invoices
+          </Title>
+        </Group>
+
+        {/* Summary strip */}
+        <Group gap="md" wrap="wrap" align="stretch">
+          <StatCard
+            label="Outstanding"
+            hint="awaiting payment"
+            value={stats.outstanding}
+            icon={Wallet}
+            color="edr-accent"
+          />
+          <StatCard
+            label="Overdue"
+            hint="past due date"
+            value={stats.overdue}
+            icon={AlertTriangle}
+            color="red"
+          />
+          <StatCard
+            label="Total invoices"
+            value={stats.total}
+            icon={FileStack}
+            color="violet"
+          />
+        </Group>
+
+        {/* Search + filters */}
+        <Paper withBorder radius="lg" p="sm" style={{ borderColor: BORDER }}>
+          <Group gap={10} wrap="wrap" align="center">
+            <TextInput
+              placeholder="Search by number, source or reference…"
+              leftSection={<Search size={16} />}
+              value={query}
+              onChange={(e) => {
+                setQuery(e.currentTarget.value);
+                resetPage();
+              }}
+              radius="md"
+              styles={{ input: { height: 42 } }}
+              style={{ flex: 1, minWidth: 220, maxWidth: 380 }}
+            />
+            <Select
+              placeholder="Any status"
+              data={[
+                { value: Freight.InvoiceStatus.Pending, label: "Due" },
+                { value: Freight.InvoiceStatus.Overdue, label: "Overdue" },
+                { value: Freight.InvoiceStatus.Paid, label: "Paid" },
+                { value: Freight.InvoiceStatus.Draft, label: "Draft" },
+                { value: Freight.InvoiceStatus.Cancelled, label: "Cancelled" },
+                { value: Freight.InvoiceStatus.Refunded, label: "Refunded" },
+              ]}
+              value={statusFilter}
+              onChange={(v) => {
+                setStatusFilter(v);
+                resetPage();
+              }}
+              clearable
+              radius="md"
+              comboboxProps={{ withinPortal: true }}
+              style={{ width: 160 }}
+              styles={{ input: { height: 42 } }}
+              aria-label="Filter by status"
+            />
+            {hasFilters && (
+              <Button
+                variant="subtle"
+                color="gray"
+                radius="md"
+                leftSection={<X size={14} />}
+                onClick={() => {
+                  setQuery("");
+                  setStatusFilter(null);
+                  resetPage();
+                }}
+                styles={{ root: { fontWeight: 600 } }}
+              >
+                Clear
+              </Button>
+            )}
+          </Group>
+        </Paper>
+
+        {/* Table */}
+        <Paper
+          withBorder
+          radius="lg"
+          style={{ borderColor: BORDER, overflow: "hidden" }}
+        >
+          <Box style={{ overflowX: "auto" }}>
+            <Table
+              verticalSpacing={14}
+              horizontalSpacing={20}
+              highlightOnHover
+              highlightOnHoverColor="#F4FBF8"
+              styles={{
+                th: {
+                  fontSize: 11,
+                  fontWeight: 700,
+                  letterSpacing: "0.05em",
+                  textTransform: "uppercase",
+                  color: MUTED,
+                  background: "#F8FAFC",
+                  borderBottom: `1px solid ${BORDER}`,
+                  whiteSpace: "nowrap",
+                  position: "sticky",
+                  top: 0,
+                  zIndex: 1,
+                },
+                tr: { transition: "background-color 120ms ease" },
+                td: {
+                  borderBottom: `1px solid ${BORDER}`,
+                  verticalAlign: "middle",
+                },
+              }}
+            >
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th>Invoice</Table.Th>
+                  <Table.Th>Billed To</Table.Th>
+                  <Table.Th>Source</Table.Th>
+                  <Table.Th ta="right">Amount</Table.Th>
+                  <Table.Th>Issued</Table.Th>
+                  <Table.Th>Due</Table.Th>
+                  <Table.Th>Status</Table.Th>
+                  <Table.Th ta="right">Action</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {isLoading && (
+                  <Table.Tr>
+                    <Table.Td colSpan={8}>
+                      <Center py={48}>
+                        <Loader color="edr-green" size="sm" />
+                      </Center>
+                    </Table.Td>
+                  </Table.Tr>
+                )}
+
+                {!isLoading && isError && (
+                  <Table.Tr>
+                    <Table.Td colSpan={8}>
+                      <Center py={48}>
+                        <Text fz={13} c="red">
+                          Failed to load invoices. Please try again.
+                        </Text>
+                      </Center>
+                    </Table.Td>
+                  </Table.Tr>
+                )}
+
+                {!isLoading && !isError && pageRows.length === 0 && (
+                  <Table.Tr>
+                    <Table.Td colSpan={8}>
+                      <Stack align="center" gap={8} py={48}>
+                        <Inbox size={26} color={MUTED} style={{ opacity: 0.5 }} />
+                        <Text fz={13} c="dimmed">
+                          {hasFilters
+                            ? "No invoices match your filters."
+                            : "No invoices yet."}
+                        </Text>
+                      </Stack>
+                    </Table.Td>
+                  </Table.Tr>
+                )}
+
+                {!isLoading &&
+                  !isError &&
+                  pageRows.map((inv) => {
+                    const payable = isPayable(inv.status);
+                    return (
+                      <Table.Tr
+                        key={inv.id}
+                        style={{ cursor: "pointer" }}
+                        onClick={() => navigate(`/billing/${inv.id}`)}
+                      >
+                        <Table.Td>
+                          <Group gap={10} wrap="nowrap" align="center">
+                            <Box
+                              style={{
+                                display: "flex",
+                                alignItems: "center",
+                                justifyContent: "center",
+                                width: 34,
+                                height: 34,
+                                borderRadius: 9,
+                                background: "#E6F7EF",
+                                color: GREEN,
+                                flexShrink: 0,
+                              }}
+                            >
+                              <Receipt size={16} />
+                            </Box>
+                            <Box>
+                              <Text fz={14} fw={700} style={{ color: INK }}>
+                                {inv.invoiceNumber}
+                              </Text>
+                              <Text fz={12} c="dimmed">
+                                {titleCase(inv.type)}
+                              </Text>
+                            </Box>
+                          </Group>
+                        </Table.Td>
+                        <Table.Td>
+                          <Text fz={13} style={{ color: INK }}>
+                            {billedTo(inv)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td>
+                          <Text fz={13} style={{ color: INK }}>
+                            {titleCase(inv.source)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Text fz={13} fw={700} style={{ color: INK }}>
+                            {formatCurrency(Number(inv.totalAmount), inv.currency)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td>
+                          <Text
+                            fz={13}
+                            c={inv.issuedAt ? undefined : "dimmed"}
+                            style={{ color: inv.issuedAt ? INK : undefined }}
+                          >
+                            {fmtDate(inv.issuedAt)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td>
+                          <Text fz={13} style={{ color: INK }}>
+                            {fmtDate(inv.dueAt)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td>
+                          <InvoiceStatusBadge status={inv.status} />
+                        </Table.Td>
+                        <Table.Td>
+                          <Group justify="flex-end" gap={8} wrap="nowrap">
+                            <Button
+                              size="sm"
+                              radius="md"
+                              h={34}
+                              variant={payable ? "filled" : "light"}
+                              color="edr-green"
+                              leftSection={
+                                payable ? (
+                                  <CreditCard size={15} />
+                                ) : (
+                                  <Eye size={15} />
+                                )
+                              }
+                              onClick={(e) => {
+                                e.stopPropagation();
+                                navigate(`/billing/${inv.id}`);
+                              }}
+                              styles={{
+                                root: {
+                                  fontWeight: 600,
+                                  fontSize: 13,
+                                  paddingInline: 14,
+                                  whiteSpace: "nowrap",
+                                  boxShadow: payable
+                                    ? "0 1px 2px rgba(14,163,113,0.25)"
+                                    : "none",
+                                },
+                              }}
+                            >
+                              {payable ? "Pay" : "View"}
+                            </Button>
+                          </Group>
+                        </Table.Td>
+                      </Table.Tr>
+                    );
+                  })}
+              </Table.Tbody>
+            </Table>
+          </Box>
+
+          {/* Pagination footer */}
+          {!isLoading && !isError && total > 0 && (
+            <Group
+              justify="space-between"
+              align="center"
+              wrap="wrap"
+              gap="md"
+              px={20}
+              py={14}
+              style={{ borderTop: `1px solid ${BORDER}`, background: "#FCFDFE" }}
+            >
+              <Group gap={10} align="center">
+                <Text fz={13} c="dimmed">
+                  Rows
+                </Text>
+                <Select
+                  data={PAGE_SIZES}
+                  value={String(pageSize)}
+                  onChange={(v) => {
+                    if (!v) return;
+                    setPageSize(Number(v));
+                    setPageIndex(0);
+                  }}
+                  radius="md"
+                  size="xs"
+                  comboboxProps={{ withinPortal: true }}
+                  style={{ width: 76 }}
+                  allowDeselect={false}
+                />
+                <Text fz={13} c="dimmed">
+                  {start}–{end} of {total}
+                </Text>
+              </Group>
+
+              <Group gap={6} align="center">
+                <PagerButton
+                  icon={<ChevronLeft size={16} />}
+                  disabled={clampedIndex === 0}
+                  onClick={() => goToPage(clampedIndex - 1)}
+                  ariaLabel="Previous page"
+                />
+                {pageNumbers(clampedIndex, pageCount).map((p, i) =>
+                  p === "…" ? (
+                    <Text key={`gap-${i}`} fz={13} c="dimmed" px={4}>
+                      …
+                    </Text>
+                  ) : (
+                    <PageChip
+                      key={p}
+                      page={p}
+                      active={p === clampedIndex}
+                      onClick={() => goToPage(p)}
+                    />
+                  ),
+                )}
+                <PagerButton
+                  icon={<ChevronRight size={16} />}
+                  disabled={clampedIndex >= pageCount - 1}
+                  onClick={() => goToPage(clampedIndex + 1)}
+                  ariaLabel="Next page"
+                />
+              </Group>
+            </Group>
+          )}
+        </Paper>
+      </Stack>
+    </Box>
+  );
+}
+
+/** Compact page-number window with ellipses: 1 … 4 5 6 … 12. */
+function pageNumbers(active: number, count: number): (number | "…")[] {
+  if (count <= 7) return Array.from({ length: count }, (_, i) => i);
+  const out: (number | "…")[] = [0];
+  const lo = Math.max(1, active - 1);
+  const hi = Math.min(count - 2, active + 1);
+  if (lo > 1) out.push("…");
+  for (let i = lo; i <= hi; i++) out.push(i);
+  if (hi < count - 2) out.push("…");
+  out.push(count - 1);
+  return out;
+}
+
+function PageChip({
+  page,
+  active,
+  onClick,
+}: {
+  page: number;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <Box
+      component="button"
+      onClick={onClick}
+      style={{
+        minWidth: 32,
+        height: 32,
+        padding: "0 8px",
+        borderRadius: 9,
+        border: `1px solid ${active ? GREEN : BORDER}`,
+        background: active ? GREEN : "#FFFFFF",
+        color: active ? "#FFFFFF" : INK,
+        fontSize: 13,
+        fontWeight: active ? 700 : 600,
+        cursor: "pointer",
+        transition: "all 120ms ease",
+      }}
+    >
+      {page + 1}
+    </Box>
+  );
+}
+
+function PagerButton({
+  icon,
+  disabled,
+  onClick,
+  ariaLabel,
+}: {
+  icon: React.ReactNode;
+  disabled: boolean;
+  onClick: () => void;
+  ariaLabel: string;
+}) {
+  return (
+    <Box
+      component="button"
+      aria-label={ariaLabel}
+      onClick={onClick}
+      disabled={disabled}
+      style={{
+        width: 32,
+        height: 32,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        borderRadius: 9,
+        border: `1px solid ${BORDER}`,
+        background: "#FFFFFF",
+        color: disabled ? "#C2CCD6" : INK,
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.6 : 1,
+        transition: "all 120ms ease",
+      }}
+    >
+      {icon}
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/NewInvoicePage.tsx b/apps/edr-freight-web/portal/src/pages/billing/NewInvoicePage.tsx
deleted file mode 100644
index 3e78132cd..000000000
--- a/apps/edr-freight-web/portal/src/pages/billing/NewInvoicePage.tsx
+++ /dev/null
@@ -1,202 +0,0 @@
-import type { ReactNode } from "react";
-import { Calendar, DollarSign, Hash } from "lucide-react";
-
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-  DialogTrigger,
-} from "@/components/ui/dialog";
-import { Input } from "@/components/ui/input";
-import { Label } from "@/components/ui/label";
-import { Button } from "@/components/ui/button";
-import { Textarea } from "@/components/ui/textarea";
-
-import { customers } from "../customers/customers.mock";
-import { bookings } from "../bookings/bookings.mock";
-import type { Currency, InvoiceStatus } from "./invoices.mock";
-
-export interface InvoiceFormData {
-  number?: string;
-  customerId?: number;
-  bookingReference?: string;
-  amount?: number;
-  currency?: Currency;
-  status?: InvoiceStatus;
-  issueDate?: string;
-  dueDate?: string;
-  notes?: string;
-}
-
-export interface NewInvoicePageProps {
-  mode?: "create" | "edit";
-  invoice?: InvoiceFormData;
-  children?: ReactNode;
-}
-
-const selectClass =
-  "flex h-10 w-full rounded-md border border-slate-200 bg-white px-3 py-2 text-sm text-slate-700 shadow-xs outline-none transition hover:border-slate-300 focus:border-[#10B981]/50 focus:ring-2 focus:ring-[#10B981]/20";
-
-export default function NewInvoicePage({
-  mode = "create",
-  invoice,
-  children,
-}: NewInvoicePageProps = {}) {
-  const isEdit = mode === "edit";
-  const title = isEdit ? "Edit Invoice" : "New Invoice";
-  const description = isEdit
-    ? "Update invoice details."
-    : "Create a new invoice for a customer booking.";
-  const submitLabel = isEdit ? "Save Changes" : "Create Invoice";
-
-  return (
-    <Dialog>
-      <DialogTrigger asChild>
-        {children ?? <Button>{isEdit ? "Edit" : "New Invoice"}</Button>}
-      </DialogTrigger>
-
-      <DialogContent className="max-h-[90vh] overflow-y-auto sm:max-w-3xl rounded-3xl">
-        <DialogHeader>
-          <DialogTitle className="text-2xl font-bold">{title}</DialogTitle>
-          <DialogDescription>{description}</DialogDescription>
-        </DialogHeader>
-
-        <div className="grid gap-5 py-4 md:grid-cols-2">
-          {/* Invoice Number */}
-          <div className="space-y-2">
-            <Label>Invoice Number *</Label>
-            <div className="relative">
-              <Hash className="absolute left-3 top-3 h-4 w-4 text-slate-400" />
-              <Input
-                defaultValue={invoice?.number ?? ""}
-                placeholder="e.g. INV-2026-0001"
-                className="pl-10"
-              />
-            </div>
-          </div>
-
-          {/* Status */}
-          <div className="space-y-2">
-            <Label>Status</Label>
-            <select
-              defaultValue={invoice?.status ?? "Draft"}
-              className={selectClass}
-            >
-              <option>Draft</option>
-              <option>Sent</option>
-              <option>Paid</option>
-              <option>Overdue</option>
-              <option>Cancelled</option>
-            </select>
-          </div>
-
-          {/* Customer */}
-          <div className="space-y-2">
-            <Label>Customer *</Label>
-            <select
-              defaultValue={invoice?.customerId ?? ""}
-              className={selectClass}
-            >
-              <option value="" disabled>
-                Select customer
-              </option>
-              {customers.map((c) => (
-                <option key={c.id} value={c.id}>
-                  {c.company}
-                </option>
-              ))}
-            </select>
-          </div>
-
-          {/* Booking */}
-          <div className="space-y-2">
-            <Label>Booking Reference</Label>
-            <select
-              defaultValue={invoice?.bookingReference ?? ""}
-              className={selectClass}
-            >
-              <option value="">No linked booking</option>
-              {bookings.map((b) => (
-                <option key={b.id} value={b.reference}>
-                  {b.reference} — {b.customer}
-                </option>
-              ))}
-            </select>
-          </div>
-
-          {/* Amount */}
-          <div className="space-y-2">
-            <Label>Amount *</Label>
-            <div className="relative">
-              <DollarSign className="absolute left-3 top-3 h-4 w-4 text-slate-400" />
-              <Input
-                type="number"
-                min={0}
-                step="0.01"
-                defaultValue={invoice?.amount ?? 0}
-                className="pl-10"
-              />
-            </div>
-          </div>
-
-          {/* Currency */}
-          <div className="space-y-2">
-            <Label>Currency</Label>
-            <select
-              defaultValue={invoice?.currency ?? "USD"}
-              className={selectClass}
-            >
-              <option>USD</option>
-              <option>ETB</option>
-              <option>DJF</option>
-            </select>
-          </div>
-
-          {/* Issue Date */}
-          <div className="space-y-2">
-            <Label>Issue Date *</Label>
-            <div className="relative">
-              <Calendar className="absolute left-3 top-3 h-4 w-4 text-slate-400" />
-              <Input
-                type="date"
-                defaultValue={invoice?.issueDate ?? ""}
-                className="pl-10"
-              />
-            </div>
-          </div>
-
-          {/* Due Date */}
-          <div className="space-y-2">
-            <Label>Due Date *</Label>
-            <div className="relative">
-              <Calendar className="absolute left-3 top-3 h-4 w-4 text-slate-400" />
-              <Input
-                type="date"
-                defaultValue={invoice?.dueDate ?? ""}
-                className="pl-10"
-              />
-            </div>
-          </div>
-
-          {/* Notes */}
-          <div className="space-y-2 md:col-span-2">
-            <Label>Notes</Label>
-            <Textarea
-              defaultValue={invoice?.notes ?? ""}
-              placeholder="Payment terms, references, etc."
-            />
-          </div>
-        </div>
-
-        <div className="flex justify-end gap-3">
-          <Button variant="outline">Cancel</Button>
-          <Button className="bg-[#10B981] text-white hover:bg-[#10B981]/90">
-            {submitLabel}
-          </Button>
-        </div>
-      </DialogContent>
-    </Dialog>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/invoice-ui.tsx b/apps/edr-freight-web/portal/src/pages/billing/invoice-ui.tsx
new file mode 100644
index 000000000..1e19b1c9a
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/billing/invoice-ui.tsx
@@ -0,0 +1,60 @@
+import { Box } from "@mantine/core";
+import { Freight } from "@edr/types";
+
+import type { PortalInvoice } from "@/services/invoices.service";
+
+/** Statuses a customer can still pay. */
+export const PAYABLE_STATUSES: Freight.InvoiceStatus[] = [
+  Freight.InvoiceStatus.Pending,
+  Freight.InvoiceStatus.Overdue,
+];
+
+export const isPayable = (status: Freight.InvoiceStatus) =>
+  PAYABLE_STATUSES.includes(status);
+
+const STATUS_STYLE: Record<
+  Freight.InvoiceStatus,
+  { label: string; bg: string; fg: string }
+> = {
+  [Freight.InvoiceStatus.Draft]: { label: "Draft", bg: "#EEF2F6", fg: "#64748B" },
+  [Freight.InvoiceStatus.Pending]: { label: "Due", bg: "#FEF3E2", fg: "#B45309" },
+  [Freight.InvoiceStatus.Paid]: { label: "Paid", bg: "#E6F7EF", fg: "#0A6F4D" },
+  [Freight.InvoiceStatus.Overdue]: { label: "Overdue", bg: "#FDECEC", fg: "#C0392B" },
+  [Freight.InvoiceStatus.Cancelled]: { label: "Cancelled", bg: "#EEF2F6", fg: "#64748B" },
+  [Freight.InvoiceStatus.Refunded]: { label: "Refunded", bg: "#EAF1FB", fg: "#2563EB" },
+};
+
+export function InvoiceStatusBadge({ status }: { status: Freight.InvoiceStatus }) {
+  const s = STATUS_STYLE[status] ?? { label: status, bg: "#EEF2F6", fg: "#64748B" };
+  return (
+    <Box
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        padding: "4px 10px",
+        borderRadius: 999,
+        background: s.bg,
+        color: s.fg,
+        fontSize: 12,
+        fontWeight: 700,
+        whiteSpace: "nowrap",
+      }}
+    >
+      {s.label}
+    </Box>
+  );
+}
+
+export const titleCase = (v: string) =>
+  v ? v.charAt(0).toUpperCase() + v.slice(1).toLowerCase() : "—";
+
+/** Best label for who an invoice is billed to (profile ref → profile type → company). */
+export function billedTo(inv: PortalInvoice): string {
+  const profile = inv.companyProfile;
+  if (profile?.reference) return profile.reference;
+  if (profile?.type) return titleCase(profile.type);
+  return inv.company?.name ?? "—";
+}
+
+export const fmtDate = (v: string | null | undefined) =>
+  v ? new Date(v).toLocaleDateString() : "—";
diff --git a/apps/edr-freight-web/portal/src/pages/billing/invoices.mock.ts b/apps/edr-freight-web/portal/src/pages/billing/invoices.mock.ts
deleted file mode 100644
index 91af9cdac..000000000
--- a/apps/edr-freight-web/portal/src/pages/billing/invoices.mock.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { customers } from "../customers/customers.mock";
-import { bookings } from "../bookings/bookings.mock";
-
-export type InvoiceStatus =
-  | "Draft"
-  | "Sent"
-  | "Paid"
-  | "Overdue"
-  | "Cancelled";
-
-export type Currency = "USD" | "ETB" | "DJF";
-
-export interface Invoice {
-  id: number;
-  number: string;
-  customerId: number;
-  customer: string;
-  bookingReference: string;
-  amount: number;
-  currency: Currency;
-  status: InvoiceStatus;
-  issueDate: string;
-  dueDate: string;
-  paidDate: string | null;
-  notes: string;
-}
-
-const statuses: InvoiceStatus[] = [
-  "Draft",
-  "Sent",
-  "Paid",
-  "Overdue",
-  "Cancelled",
-];
-const currencies: Currency[] = ["USD", "ETB", "DJF"];
-
-export const invoices: Invoice[] = Array.from({ length: 24 }, (_, i) => {
-  const customer = customers[i % customers.length] as (typeof customers)[number];
-  const booking = bookings[i % bookings.length] as (typeof bookings)[number];
-  const id = i + 1;
-  const issue = new Date(2026, 3, 1 + (i % 28));
-  const due = new Date(issue);
-  due.setDate(due.getDate() + 30);
-  const status = statuses[i % statuses.length] as InvoiceStatus;
-  const currency = currencies[i % currencies.length] as Currency;
-  const baseAmount = 5000 + (i * 1234) % 25000;
-  return {
-    id,
-    number: `INV-2026-${String(id).padStart(4, "0")}`,
-    customerId: customer.id,
-    customer: customer.company,
-    bookingReference: booking.reference,
-    amount: Math.round(baseAmount * 100) / 100,
-    currency,
-    status,
-    issueDate: issue.toISOString().slice(0, 10),
-    dueDate: due.toISOString().slice(0, 10),
-    paidDate:
-      status === "Paid"
-        ? new Date(due.getTime() - 86400000 * (i % 7))
-            .toISOString()
-            .slice(0, 10)
-        : null,
-    notes:
-      i % 3 === 0
-        ? "Net 30 payment terms."
-        : i % 3 === 1
-        ? "Bank transfer preferred."
-        : "Payment due upon receipt.",
-  };
-});
-
-export function getInvoiceById(id: number | string): Invoice | undefined {
-  const numericId = typeof id === "string" ? Number(id) : id;
-  return invoices.find((inv) => inv.id === numericId);
-}
-
-export function formatCurrency(amount: number, currency: Currency): string {
-  const symbols: Record<Currency, string> = {
-    USD: "$",
-    ETB: "Br",
-    DJF: "DJF",
-  };
-  return `${symbols[currency]} ${amount.toLocaleString(undefined, {
-    minimumFractionDigits: 2,
-    maximumFractionDigits: 2,
-  })}`;
-}
diff --git a/apps/edr-freight-web/portal/src/services/api.ts b/apps/edr-freight-web/portal/src/services/api.ts
index 4bb5e16e8..1526e69b6 100644
--- a/apps/edr-freight-web/portal/src/services/api.ts
+++ b/apps/edr-freight-web/portal/src/services/api.ts
@@ -30,6 +30,12 @@ import {
   IntentStatus,
 } from "./payments.service";
 import { consignmentsService } from "./consignments.service";
+import {
+  invoicesService,
+  PortalInvoice,
+  PortalInvoiceDetail,
+  PayInvoicePayload,
+} from "./invoices.service";
 import { trackingService } from "./tracking.service";
 import { fileUploadSettingsService } from "./fileUploadSettings.service";
 import { dropdownSettingsService } from "./dropdownSettings.service";
@@ -597,4 +603,23 @@ export const api = {
       ({ optionId }) => dropdownSettingsService.removeOption(optionId),
     ),
   },
+
+  invoices: {
+    listMy: endpoint<void, PortalInvoice[]>(
+      "invoices",
+      "listMy",
+      invoicesService.listMy,
+    ),
+
+    get: endpoint<{ id: string }, PortalInvoiceDetail>(
+      "invoices",
+      "get",
+      ({ id }) => invoicesService.get(id),
+    ),
+
+    pay: endpoint<
+      { id: string; payload?: PayInvoicePayload },
+      InitiateResponse
+    >("invoices", "pay", ({ id, payload }) => invoicesService.pay(id, payload)),
+  },
 };
diff --git a/apps/edr-freight-web/portal/src/services/invoices.service.ts b/apps/edr-freight-web/portal/src/services/invoices.service.ts
new file mode 100644
index 000000000..f6b11e2ea
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/services/invoices.service.ts
@@ -0,0 +1,89 @@
+import type { Freight } from "@edr/types";
+
+import { URL_CONSTANTS } from "@/constants/URLS";
+import { client } from "../utils/api";
+import type { InitiateResponse } from "./payments.service";
+
+const B = URL_CONSTANTS.BILLING;
+
+export interface InvoiceCompany {
+  id: string;
+  name: string;
+}
+
+export interface InvoiceCompanyProfile {
+  id: string;
+  type: string;
+  reference: string | null;
+}
+
+/**
+ * A customer-facing invoice row, as returned by `GET /billing/my-invoices`.
+ * Mirrors the freight `Invoice` entity (the shared `Freight.IInvoice` type is
+ * stale and intentionally not reused here).
+ */
+export interface PortalInvoice {
+  id: string;
+  invoiceNumber: string;
+  totalAmount: number;
+  currency: string;
+  status: Freight.InvoiceStatus;
+  /** Originating subsystem: booking / warehouse / demurrage. */
+  source: string;
+  sourceId: string;
+  /** What the invoice bills for (e.g. PREPAID). */
+  type: string;
+  issuedAt: string | null;
+  dueAt: string;
+  createdAt: string;
+  company?: InvoiceCompany;
+  companyProfile?: InvoiceCompanyProfile;
+}
+
+export interface InvoiceLine {
+  id: string;
+  chargeType: string;
+  description?: string | null;
+  quantity: number;
+  unitRate: number;
+  amount: number;
+  currency: string;
+}
+
+export interface PortalInvoiceDetail extends PortalInvoice {
+  lines: InvoiceLine[];
+}
+
+export interface PayInvoicePayload {
+  method?: string;
+  platform?: "web" | "mobile";
+  payerAccount?: string;
+  returnUrl?: string;
+  failureUrl?: string;
+}
+
+export const invoicesService = {
+  /** Every invoice billed to the signed-in customer's company, newest first. */
+  listMy: async (): Promise<PortalInvoice[]> => {
+    const { data } = await client.get(B.MY_INVOICES);
+    return data.data ?? data;
+  },
+
+  /** One of the customer's invoices, with its line items. */
+  get: async (id: string): Promise<PortalInvoiceDetail> => {
+    const { data } = await client.get(B.MY_INVOICE_BY_ID(id));
+    return data.data ?? data;
+  },
+
+  /** Initiate gateway payment for an open invoice; returns the client action. */
+  pay: async (
+    id: string,
+    payload: PayInvoicePayload = {},
+  ): Promise<InitiateResponse> => {
+    const { data } = await client.post(B.PAY_INVOICE(id), {
+      platform: "web",
+      ...payload,
+    });
+    return data.data ?? data;
+  },
+};

From 7dba546254a51bf25342969dd7f0a269dcf63ca5 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 13:59:51 +0000
Subject: [PATCH 20/63] fix

---
 .../src/modules/first-mile/entities/first-mile.entity.ts      | 4 ++--
 .../src/modules/last-mile/entities/last-mile.entity.ts        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
index 513aaf98e..e810d23cc 100644
--- a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
@@ -34,8 +34,8 @@ export class FirstMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  @Column({ type: 'boolean', default: false })
-  isPostPaymentCompleted!: boolean;
+  // @Column({ type: 'boolean', default: false })
+  // isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;
diff --git a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
index 6c8c9d1ca..ad4b789f4 100644
--- a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
@@ -34,8 +34,8 @@ export class LastMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  @Column({ type: 'boolean', default: false })
-  isPostPaymentCompleted!: boolean;
+  // @Column({ type: 'boolean', default: false })
+  // isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;

From e9f9450b0f85272421ce1c250b8cfa14adc5144c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 14:10:10 +0000
Subject: [PATCH 21/63] fix: types

---
 .../portal/src/services/invoices.service.ts   | 52 +++---------------
 packages/types/src/freight/index.ts           | 53 +++++++++++++++++--
 2 files changed, 54 insertions(+), 51 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/services/invoices.service.ts b/apps/edr-freight-web/portal/src/services/invoices.service.ts
index f6b11e2ea..99b1d0dee 100644
--- a/apps/edr-freight-web/portal/src/services/invoices.service.ts
+++ b/apps/edr-freight-web/portal/src/services/invoices.service.ts
@@ -6,53 +6,13 @@ import type { InitiateResponse } from "./payments.service";
 
 const B = URL_CONSTANTS.BILLING;
 
-export interface InvoiceCompany {
-  id: string;
-  name: string;
-}
+/** A customer-facing invoice row, as returned by `GET /billing/my-invoices`. */
+export type PortalInvoice = Freight.IInvoice;
 
-export interface InvoiceCompanyProfile {
-  id: string;
-  type: string;
-  reference: string | null;
-}
-
-/**
- * A customer-facing invoice row, as returned by `GET /billing/my-invoices`.
- * Mirrors the freight `Invoice` entity (the shared `Freight.IInvoice` type is
- * stale and intentionally not reused here).
- */
-export interface PortalInvoice {
-  id: string;
-  invoiceNumber: string;
-  totalAmount: number;
-  currency: string;
-  status: Freight.InvoiceStatus;
-  /** Originating subsystem: booking / warehouse / demurrage. */
-  source: string;
-  sourceId: string;
-  /** What the invoice bills for (e.g. PREPAID). */
-  type: string;
-  issuedAt: string | null;
-  dueAt: string;
-  createdAt: string;
-  company?: InvoiceCompany;
-  companyProfile?: InvoiceCompanyProfile;
-}
-
-export interface InvoiceLine {
-  id: string;
-  chargeType: string;
-  description?: string | null;
-  quantity: number;
-  unitRate: number;
-  amount: number;
-  currency: string;
-}
-
-export interface PortalInvoiceDetail extends PortalInvoice {
-  lines: InvoiceLine[];
-}
+/** An invoice plus its line items, as returned by `GET /billing/my-invoices/:id`. */
+export type PortalInvoiceDetail = Freight.IInvoice & {
+  lines: Freight.IInvoiceLine[];
+};
 
 export interface PayInvoicePayload {
   method?: string;
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index e2de4519c..dbfcf655d 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -524,14 +524,57 @@ export interface ClearanceView {
   allApproved: boolean;
 }
 
-export interface IInvoice extends BaseEntity {
-  bookingId: string;
-  invoiceNumber: string;
+/** Company an invoice is billed to (minimal projection). */
+export interface IInvoiceCompany {
+  id: string;
+  name: string;
+}
+
+/** Company profile (importer/exporter/forwarder/…) an invoice is billed to. */
+export interface IInvoiceCompanyProfile {
+  id: string;
+  type: string;
+  reference: string | null;
+}
+
+/** A single billed line on an invoice. */
+export interface IInvoiceLine extends BaseEntity {
+  invoiceId: string;
+  chargeType: string;
+  description?: string | null;
+  /** Units billed (container count, wagon count, tons, …); defaults to 1. */
+  quantity: number;
+  /** Price per unit; `amount` is normally `quantity * unitRate`. */
+  unitRate: number;
   amount: number;
   currency: string;
-  status: PaymentStatus;
-  issuedAt: string;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface IInvoice extends BaseEntity {
+  invoiceNumber: string;
+  /** Customer (company) the invoice is billed to. */
+  companyId: string;
+  company?: IInvoiceCompany;
+  /** Specific company profile billed. */
+  companyProfileId: string;
+  companyProfile?: IInvoiceCompanyProfile;
+  totalAmount: number;
+  currency: string;
+  status: InvoiceStatus;
+  /** Originating subsystem: booking / warehouse / demurrage. */
+  source: InvoiceSource;
+  /** Identifier of the source record (e.g. booking id). */
+  sourceId: string;
+  /** What the invoice bills for (e.g. PREPAID). */
+  type: string;
+  /** Set when issued; null while DRAFT. */
+  issuedAt?: string | null;
+  /** Gateway payment that settled the invoice, once paid. */
+  paymentId?: string | null;
   dueAt: string;
+  /** Present on invoice-detail reads. */
+  lines?: IInvoiceLine[];
 }
 
 // ── Reference Data (booking form catalog) ──────────────────────────────────────

From feae27d0c3964acc5a848695fa9b84c2d15ae153 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 14:16:31 +0000
Subject: [PATCH 22/63] feat: improve the invoices in the portal

---
 .../src/pages/MyPortalPage/MyPortalPage.tsx   |   3 +-
 .../components/InvoicesSection.tsx            | 131 +++++++++---------
 2 files changed, 64 insertions(+), 70 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
index fccc4d98f..c9e073eb5 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/MyPortalPage.tsx
@@ -34,7 +34,6 @@ export default function MyPortalPage() {
     totalOutstanding,
     companyName,
     greeting,
-    recentInvoices,
     dashboard,
     volumePoints,
     maxVolume,
@@ -120,7 +119,7 @@ export default function MyPortalPage() {
         </Grid.Col>
 
         <Grid.Col span={{ base: 12, lg: 4 }}>
-          <InvoicesSection invoices={recentInvoices} />
+          <InvoicesSection invoices={outstandingInvoices} />
         </Grid.Col>
       </Grid>
 
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
index 22362c816..8d350b93f 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/InvoicesSection.tsx
@@ -2,7 +2,7 @@ import { formatCurrency } from "@/lib/currency";
 import type { PortalInvoice } from "@/services/invoices.service";
 import { Box, Group, Stack, Text } from "@mantine/core";
 import { Freight } from "@edr/types";
-import { CheckCircle2, ChevronRight, Clock3, Zap } from "lucide-react";
+import { ChevronRight, Clock3 } from "lucide-react";
 import { memo } from "react";
 import { Link } from "react-router-dom";
 import { cv, INVOICE_BADGE } from "../constants";
@@ -13,18 +13,22 @@ interface InvoicesSectionProps {
   invoices: PortalInvoice[];
 }
 
+/** Max rows to list in the compact dashboard card. */
+const MAX_ROWS = 5;
+
 const titleCase = (v: string) =>
   v ? v.charAt(0).toUpperCase() + v.slice(1).toLowerCase() : "";
 
 export const InvoicesSection = memo(function InvoicesSection({
   invoices,
 }: InvoicesSectionProps) {
-  const outstandingInvoices = invoices.filter(
+  // Dashboard shows unpaid invoices only (pending + overdue).
+  const pendingInvoices = invoices.filter(
     (inv) =>
       inv.status === Freight.InvoiceStatus.Pending ||
       inv.status === Freight.InvoiceStatus.Overdue,
   );
-  const totalOutstanding = outstandingInvoices.reduce(
+  const totalOutstanding = pendingInvoices.reduce(
     (sum, inv) => sum + Number(inv.totalAmount),
     0,
   );
@@ -52,83 +56,74 @@ export const InvoicesSection = memo(function InvoicesSection({
         <Text fz={24} fw={800} mt={4} c="edr-text">
           {formatCurrency(totalOutstanding || 0, "ETB")}
         </Text>
-        <Group justify="space-between" align="center" mt={8} wrap="nowrap">
-          <Text fz={12} c="edr-amber-text">
-            {outstandingInvoices.length} invoices unpaid
-          </Text>
-          <Group
-            gap={5}
-            align="center"
-            px={14}
-            py={8}
-            bg="edr-accent"
-            className="cursor-pointer rounded-[9px]"
-          >
-            <Zap size={15} color="#fff" />
-            <Text fz={13} fw={700} c="white">
-              Pay all
-            </Text>
-          </Group>
-        </Group>
+        <Text fz={12} mt={8} c="edr-amber-text">
+          {pendingInvoices.length} invoices unpaid
+        </Text>
       </Box>
 
-      {invoices.length === 0 ? (
-        <EmptyState message="No invoices yet." />
+      {pendingInvoices.length === 0 ? (
+        <EmptyState message="No pending invoices." />
       ) : (
         <Stack gap={0}>
-          {invoices.map((invoice, i) => {
+          {pendingInvoices.slice(0, MAX_ROWS).map((invoice, i) => {
             const badge = INVOICE_BADGE[invoice.status];
-            const isPaid = invoice.status === Freight.InvoiceStatus.Paid;
             const isOverdue = invoice.status === Freight.InvoiceStatus.Overdue;
-            const dueText = isPaid
-              ? "Paid"
-              : isOverdue
-                ? "Overdue"
-                : `Due ${new Date(invoice.dueAt).toLocaleDateString()}`;
-            const DueIcon = isPaid ? CheckCircle2 : Clock3;
-            const dueIconColor = isPaid ? cv("edr-green.5") : cv("edr-muted");
+            const dueText = isOverdue
+              ? "Overdue"
+              : `Due ${new Date(invoice.dueAt).toLocaleDateString()}`;
+            const dueIconColor = isOverdue ? cv("edr-red") : cv("edr-muted");
 
             return (
               <Box key={invoice.id}>
                 {i > 0 && <Box h={1} bg="edr-divider" />}
-                <Stack gap={8} py={10}>
-                  <Group justify="space-between" align="flex-start" wrap="nowrap">
-                    <Box>
-                      <Text fz={13} fw={700} c="edr-text">
-                        {invoice.invoiceNumber}
-                      </Text>
-                      <Text fz={11} c="edr-muted">
-                        {titleCase(invoice.source)} · {titleCase(invoice.type)}
-                      </Text>
-                    </Box>
-                    <Text fz={14} fw={700} c="edr-text">
-                      {formatCurrency(
-                        Number(invoice.totalAmount),
-                        invoice.currency,
-                      )}
-                    </Text>
-                  </Group>
-                  <Group justify="space-between" align="center" wrap="nowrap">
-                    <Group gap={5} align="center">
-                      <DueIcon size={13} color={dueIconColor} />
-                      <Text fz={12} c="edr-muted">
-                        {dueText}
-                      </Text>
-                    </Group>
-                    {badge && (
-                      <Box
-                        bg={badge.bg}
-                        px={10}
-                        py={4}
-                        className="rounded-full"
-                      >
-                        <Text fz={11} fw={700} c={badge.text}>
-                          {badge.label}
+                <Link
+                  to={`/billing/${invoice.id}`}
+                  className="no-underline"
+                  style={{ display: "block", color: "inherit" }}
+                >
+                  <Stack
+                    gap={8}
+                    py={10}
+                    className="cursor-pointer rounded-[9px] transition-colors hover:bg-[var(--mantine-color-edr-soft-0)]"
+                  >
+                    <Group justify="space-between" align="flex-start" wrap="nowrap">
+                      <Box>
+                        <Text fz={13} fw={700} c="edr-text">
+                          {invoice.invoiceNumber}
+                        </Text>
+                        <Text fz={11} c="edr-muted">
+                          {titleCase(invoice.source)} · {titleCase(invoice.type)}
                         </Text>
                       </Box>
-                    )}
-                  </Group>
-                </Stack>
+                      <Text fz={14} fw={700} c="edr-text">
+                        {formatCurrency(
+                          Number(invoice.totalAmount),
+                          invoice.currency,
+                        )}
+                      </Text>
+                    </Group>
+                    <Group justify="space-between" align="center" wrap="nowrap">
+                      <Group gap={5} align="center">
+                        <Clock3 size={13} color={dueIconColor} />
+                        <Text fz={12} c="edr-muted">
+                          {dueText}
+                        </Text>
+                      </Group>
+                      {badge && (
+                        <Box
+                          bg={badge.bg}
+                          px={10}
+                          py={4}
+                          className="rounded-full"
+                        >
+                          <Text fz={11} fw={700} c={badge.text}>
+                            {badge.label}
+                          </Text>
+                        </Box>
+                      )}
+                    </Group>
+                  </Stack>
+                </Link>
               </Box>
             );
           })}

From 31a2e93c4918f36f78a04361afeea1f527fe12f9 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 14:42:53 +0000
Subject: [PATCH 23/63] fix: rm the hardcode false for general contract

---
 .../bookings/booking-invoice.service.ts       | 52 ++++---------------
 .../src/modules/bookings/bookings.module.ts   |  2 -
 2 files changed, 9 insertions(+), 45 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
index 6cd2f4be5..47338f196 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
@@ -10,7 +10,6 @@ import {
   InvoiceLineInput,
 } from '../billing/billing.service';
 import { Invoice } from '../billing/entities/invoice.entity';
-import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.service';
 import { FirstMileService } from '../first-mile/first-mile.service';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
 import { PriceLineItemDto } from './dto/generate-price-response.dto';
@@ -27,10 +26,6 @@ interface StoredPricingBreakdown {
 /** Round to 2 decimals, avoiding binary float drift. */
 const round2 = (n: number): number => Math.round(n * 100) / 100;
 
-/** Setting code holding the general-contract ordering window (months). */
-const CONTRACT_PERIOD_SETTING_CODE = 'general_contract_period';
-const DEFAULT_CONTRACT_PERIOD_MONTHS = 3;
-
 /**
  * Owns the booking ⇄ invoice mapping — the one place that knows how a booking
  * turns into invoices, which type to use, and how it advances when paid. Bookings
@@ -47,7 +42,6 @@ export class BookingInvoiceService {
     private readonly billing: BillingService,
     private readonly bookingsRepository: BookingsRepository,
     private readonly dataSource: DataSource,
-    private readonly dropdownSettings: DropdownSettingsService,
     @Inject(forwardRef(() => FirstMileService))
     private readonly firstMile: FirstMileService,
     @Inject(forwardRef(() => BookingBatchService))
@@ -107,11 +101,15 @@ export class BookingInvoiceService {
   }
 
   /**
-   * Advance a booking once its prepaid invoice settles. This is the domain
-   * side-effect of payment, relocated out of the payment service: a general
-   * contract becomes ACTIVE and opens its ordering window (it does not enter the
-   * train queue — nothing has been ordered yet); a normal booking becomes PAID
+   * Advance a booking once its prepaid invoice settles — the domain side-effect
+   * of payment, relocated out of the payment service: the booking becomes PAID
    * and is allocated into its batch. Idempotent — no-op when already PAID.
+   *
+   * General contracts are a separate aggregate now: their CONTRACT_ACTIVE
+   * lifecycle and ordering window live in the contracts module, advanced by the
+   * contract transition/clearance services — not by booking payment. Every
+   * booking that settles here is a ONE_TIME shipment, so there is no contract
+   * branch (legacy GENERAL_CONTRACT booking creation now 410s).
    */
   private async advanceBookingOnPayment(bookingId: string): Promise<void> {
     const booking = await this.bookingsRepository.findById(bookingId);
@@ -121,35 +119,15 @@ export class BookingInvoiceService {
     }
     if (booking.paymentStatus === 'PAID') return;
 
-    const paidAt = new Date();
-    const isGeneralContract = false
-    // booking.bookingType === 'GENERAL_CONTRACT';
-
-    let contractExpiresAt: Date | null = null;
-    if (isGeneralContract) {
-      const months = await this.contractPeriodMonths();
-      contractExpiresAt = new Date(paidAt);
-      contractExpiresAt.setMonth(contractExpiresAt.getMonth() + months);
-    }
-
     await this.dataSource.transaction(async (mg) => {
       await mg.update(
         Booking,
         { id: bookingId },
-        isGeneralContract
-          ? { paymentStatus: 'PAID', status: 'CONTRACT_ACTIVE', expiresAt: contractExpiresAt }
-          : { paymentStatus: 'PAID', status: 'PAID' },
+        { paymentStatus: 'PAID', status: 'PAID' },
       );
       await this.firstMile.acceptBooking(bookingId);
     });
 
-    if (isGeneralContract) {
-      this.logger.log(
-        `General contract ${booking.reference} ACTIVE — ordering open until ${contractExpiresAt?.toISOString()}`,
-      );
-      return;
-    }
-
     try {
       await this.bookingBatch.ensurePaidBookingAllocated(bookingId);
     } catch (err) {
@@ -159,18 +137,6 @@ export class BookingInvoiceService {
     }
   }
 
-  /** Configured general-contract ordering window in months (defaults to 3). */
-  private async contractPeriodMonths(): Promise<number> {
-    try {
-      const setting = await this.dropdownSettings.getByCode(CONTRACT_PERIOD_SETTING_CODE);
-      const months = Number(setting.children?.[0]?.value);
-      if (Number.isFinite(months) && months > 0) return months;
-    } catch {
-      // Setting not seeded — fall back to the default.
-    }
-    return DEFAULT_CONTRACT_PERIOD_MONTHS;
-  }
-
   /** Map a booking's pricing snapshot into a generic invoice request. */
   private buildInput(booking: Booking): GenerateInvoiceInput | null {
     const breakdown = (booking.pricingBreakdown ?? {}) as StoredPricingBreakdown;
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 1a12a5e6f..8be7325ba 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -11,7 +11,6 @@ import { RuleEngineModule } from '../rule-engine/rule-engine.module';
 import { FileUploadSettingsModule } from '../file-upload-settings/file-upload-settings.module';
 import { SignaturesModule } from '../signatures/signatures.module';
 import { BillingModule } from '../billing/billing.module';
-import { DropdownSettingsModule } from '../dropdown-settings/dropdown-settings.module';
 import { FirstMileModule } from '../first-mile/first-mile.module';
 import { BookingContractService } from './booking-contract.service';
 import { BookingInvoiceService } from './booking-invoice.service';
@@ -53,7 +52,6 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
       BookingContractSignature,
     ]),
     BillingModule,
-    DropdownSettingsModule,
     forwardRef(() => FirstMileModule),
     forwardRef(() => TrainSchedulingModule),
     FilesModule,

From 6fa315db0f4bad01da7eca90b87ad3f02ae26cf0 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 14:45:22 +0000
Subject: [PATCH 24/63] fix

---
 ...0002-CreateLastMileContainerAllocations.ts |  78 +++++++++
 ...00000-CreateBookingContainerAllocations.ts |  80 +++++++++
 ...000-CreateFirstMileContainerAllocations.ts |  74 ++++++++
 .../bookings/booking-allocation.controller.ts |  20 +++
 .../src/modules/bookings/bookings.module.ts   |   5 +-
 .../src/modules/bookings/bookings.service.ts  |  32 ++++
 .../bookings/dto/allocate-containers.dto.ts   |   8 +
 .../booking-container-allocation.entity.ts    |  32 ++++
 .../bookings/entities/booking.entity.ts       |   4 +
 .../first-mile/dto/allocate-containers.dto.ts |   8 +
 .../first-mile-container-allocation.entity.ts |  36 ++++
 .../first-mile/entities/first-mile.entity.ts  |  10 +-
 .../first-mile/first-mile.controller.ts       |  11 ++
 .../modules/first-mile/first-mile.module.ts   |   3 +-
 .../modules/first-mile/first-mile.service.ts  |  35 ++++
 .../last-mile/dto/allocate-containers.dto.ts  |   8 +
 .../last-mile-container-allocation.entity.ts  |  32 ++++
 .../last-mile/entities/last-mile.entity.ts    |   6 +-
 .../modules/last-mile/last-mile.controller.ts |  11 ++
 .../src/modules/last-mile/last-mile.module.ts |   3 +-
 .../modules/last-mile/last-mile.service.ts    |  35 +++-
 .../components/ContainerAllocationTable.tsx   | 164 ++++++++++++++++++
 .../FirstMileContainerAllocationTable.tsx     | 164 ++++++++++++++++++
 .../LastMileContainerAllocationTable.tsx      | 164 ++++++++++++++++++
 .../backoffice/src/constants/apiConfig.ts     |   4 +-
 .../src/pages/bookings/BookingDetailPage.tsx  |  29 ++++
 .../src/pages/operations/FirstMilePage.tsx    |  79 +++++++++
 .../src/pages/operations/LastMilePage.tsx     | 100 +++++++++++
 28 files changed, 1227 insertions(+), 8 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts
 create mode 100644 apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts
 create mode 100644 apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-allocation.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/dto/allocate-containers.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/entities/booking-container-allocation.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/first-mile/dto/allocate-containers.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/last-mile/dto/allocate-containers.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/last-mile/entities/last-mile-container-allocation.entity.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/ContainerAllocationTable.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/FirstMileContainerAllocationTable.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/LastMileContainerAllocationTable.tsx

diff --git a/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts
new file mode 100644
index 000000000..b2026b753
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts
@@ -0,0 +1,78 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create the freight.last_mile_container_allocations table — container allocation
+ * records linking last-mile deliveries with containers and vehicles.
+ */
+export class CreateLastMileContainerAllocations1810000000002 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.last_mile_container_allocations');
+    if (exists) return;
+
+    await queryRunner.createTable(
+      new Table({
+        name: 'freight.last_mile_container_allocations',
+        columns: [
+          {
+            name: 'id',
+            type: 'uuid',
+            isPrimary: true,
+            default: 'gen_random_uuid()',
+          },
+          { name: 'last_mile_id', type: 'uuid', isNullable: false },
+          { name: 'container_id', type: 'uuid', isNullable: false },
+          { name: 'vehicle_id', type: 'uuid', isNullable: true },
+          {
+            name: 'container_type',
+            type: 'text',
+            isNullable: false,
+          },
+          {
+            name: 'quantity',
+            type: 'integer',
+            default: 1,
+            isNullable: false,
+          },
+          { name: 'created_at', type: 'timestamptz', default: 'now()' },
+          { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+          { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+        ],
+      }),
+      true,
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.last_mile_container_allocations',
+      new TableForeignKey({
+        columnNames: ['last_mile_id'],
+        referencedTableName: 'freight.last_mile',
+        referencedColumnNames: ['id'],
+        onDelete: 'CASCADE',
+      }),
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.last_mile_container_allocations',
+      new TableForeignKey({
+        columnNames: ['vehicle_id'],
+        referencedTableName: 'freight.vehicles',
+        referencedColumnNames: ['id'],
+        onDelete: 'SET NULL',
+      }),
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_last_mile_container_allocations_last_mile_id" ON "freight"."last_mile_container_allocations" ("last_mile_id")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX "IDX_last_mile_container_allocations_vehicle_id" ON "freight"."last_mile_container_allocations" ("vehicle_id")`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.last_mile_container_allocations');
+    if (exists) {
+      await queryRunner.dropTable('freight.last_mile_container_allocations');
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts
new file mode 100644
index 000000000..70b0832f5
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts
@@ -0,0 +1,80 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create the freight.booking_container_allocations table — container-to-vehicle
+ * allocation mapping for flexible routing of containers across available vehicles.
+ */
+export class CreateBookingContainerAllocations1825000000000 implements MigrationInterface {
+  name = 'CreateBookingContainerAllocations1825000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.booking_container_allocations');
+    if (exists) return;
+
+    await queryRunner.createTable(
+      new Table({
+        name: 'freight.booking_container_allocations',
+        columns: [
+          {
+            name: 'id',
+            type: 'uuid',
+            isPrimary: true,
+            default: 'gen_random_uuid()',
+          },
+          { name: 'booking_id', type: 'uuid', isNullable: false },
+          { name: 'container_id', type: 'uuid', isNullable: false },
+          { name: 'vehicle_id', type: 'uuid', isNullable: true },
+          {
+            name: 'container_type',
+            type: 'text',
+            isNullable: false,
+          },
+          {
+            name: 'quantity',
+            type: 'integer',
+            default: 1,
+            isNullable: false,
+          },
+          { name: 'created_at', type: 'timestamptz', default: 'now()' },
+          { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+          { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+        ],
+      }),
+      true,
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.booking_container_allocations',
+      new TableForeignKey({
+        columnNames: ['booking_id'],
+        referencedTableName: 'freight.bookings',
+        referencedColumnNames: ['id'],
+        onDelete: 'CASCADE',
+      }),
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.booking_container_allocations',
+      new TableForeignKey({
+        columnNames: ['vehicle_id'],
+        referencedTableName: 'freight.vehicles',
+        referencedColumnNames: ['id'],
+        onDelete: 'SET NULL',
+      }),
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_booking_container_allocations_booking_id" ON "freight"."booking_container_allocations" ("booking_id")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX "IDX_booking_container_allocations_vehicle_id" ON "freight"."booking_container_allocations" ("vehicle_id")`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.booking_container_allocations');
+    if (exists) {
+      await queryRunner.dropTable('freight.booking_container_allocations');
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts
new file mode 100644
index 000000000..b91e88633
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts
@@ -0,0 +1,74 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create freight.first_mile_container_allocations table — tracks
+ * container allocations per first-mile shipment with optional vehicle assignment.
+ */
+export class CreateFirstMileContainerAllocations1830000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.first_mile_container_allocations');
+    if (exists) return;
+
+    await queryRunner.createTable(
+      new Table({
+        name: 'freight.first_mile_container_allocations',
+        columns: [
+          {
+            name: 'id',
+            type: 'uuid',
+            isPrimary: true,
+            default: 'gen_random_uuid()',
+          },
+          { name: 'first_mile_id', type: 'uuid', isNullable: false },
+          { name: 'container_id', type: 'uuid', isNullable: false },
+          { name: 'vehicle_id', type: 'uuid', isNullable: true },
+          { name: 'container_type', type: 'text', isNullable: false },
+          {
+            name: 'quantity',
+            type: 'int',
+            default: 1,
+            isNullable: false,
+          },
+          { name: 'created_at', type: 'timestamptz', default: 'now()' },
+          { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+          { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+        ],
+      }),
+      true,
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.first_mile_container_allocations',
+      new TableForeignKey({
+        columnNames: ['first_mile_id'],
+        referencedTableName: 'freight.first_mile',
+        referencedColumnNames: ['id'],
+        onDelete: 'CASCADE',
+      }),
+    );
+
+    await queryRunner.createForeignKey(
+      'freight.first_mile_container_allocations',
+      new TableForeignKey({
+        columnNames: ['vehicle_id'],
+        referencedTableName: 'freight.vehicles',
+        referencedColumnNames: ['id'],
+        onDelete: 'SET NULL',
+      }),
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_first_mile_container_allocations_first_mile_id" ON "freight"."first_mile_container_allocations" ("first_mile_id")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX "IDX_first_mile_container_allocations_vehicle_id" ON "freight"."first_mile_container_allocations" ("vehicle_id")`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const exists = await queryRunner.hasTable('freight.first_mile_container_allocations');
+    if (exists) {
+      await queryRunner.dropTable('freight.first_mile_container_allocations');
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-allocation.controller.ts b/apps/edr-freight-api/src/modules/bookings/booking-allocation.controller.ts
new file mode 100644
index 000000000..cfb9887c3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-allocation.controller.ts
@@ -0,0 +1,20 @@
+import { Body, Controller, Param, ParseUUIDPipe, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { BookingsService } from './bookings.service';
+import { AllocateContainersDto } from './dto/allocate-containers.dto';
+
+@ApiTags('bookings')
+@Controller('bookings')
+@ApiBearerAuth()
+export class BookingAllocationController {
+  constructor(private readonly bookingsService: BookingsService) {}
+
+  @Post(':bookingId/allocate-containers')
+  @ApiOperation({ summary: 'Allocate containers to vehicles' })
+  async allocateContainers(
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+    @Body() dto: AllocateContainersDto,
+  ) {
+    return this.bookingsService.allocateContainers(bookingId, dto.allocations);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index ded7d0239..b959677bd 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -16,6 +16,7 @@ import { BookingPricingService } from './booking-pricing.service';
 import { BookingReferenceDataService } from './booking-reference-data.service';
 import { BookingTransitionService } from './booking-transition.service';
 import { BookingsController } from './bookings.controller';
+import { BookingAllocationController } from './booking-allocation.controller';
 import { PayController } from './pay.controller';
 import { BookingsRepository } from './bookings.repository';
 import { ConsolidationService } from './consolidation.service';
@@ -28,6 +29,7 @@ import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingContractSignature } from './entities/booking-contract-signature.entity';
 import { BookingReviewNote } from './entities/booking-review-note.entity';
 import { Booking } from './entities/booking.entity';
+import { BookingContainerAllocation } from './entities/booking-container-allocation.entity';
 import { ContractPdfService } from '../../contracts/contract-pdf.service';
 import { ContractPricingScheduleBuilder } from '../../contracts/contract-pricing-schedule.builder';
 import { ContractRendererService } from '../../contracts/contract-renderer.service';
@@ -47,6 +49,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
       BookingRateSnapshot,
       BookingReviewNote,
       BookingContractSignature,
+      BookingContainerAllocation,
     ]),
     PaymentModule,
     forwardRef(() => TrainSchedulingModule),
@@ -63,7 +66,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
         config.get<ExchangeOptions>('app.cbeExchange') ?? {},
     }),
   ],
-  controllers: [BookingsController, PayController],
+  controllers: [BookingsController, BookingAllocationController, PayController],
   providers: [
     BookingsService,
     BookingsRepository,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 3d3bab20b..ea7eea31f 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -43,6 +43,7 @@ import {
   FreightType,
 } from './entities/booking.entity';
 import { Booking } from './entities/booking.entity';
+import { BookingContainerAllocation } from './entities/booking-container-allocation.entity';
 import { FileRecord } from '../files/entities/file.entity';
 
 /** Paginated booking list: flat `total` (backoffice) + `meta` block (portal). */
@@ -1305,4 +1306,35 @@ export class BookingsService {
       createdAt: b.createdAt,
     }));
   }
+
+  async allocateContainers(
+    bookingId: string,
+    allocations: Array<{ containerId: string; vehicleId: string }>,
+  ) {
+    const booking = await this.findById(bookingId);
+    if (!booking) {
+      throw new NotFoundException(`Booking ${bookingId} not found`);
+    }
+
+    await this.dataSource.transaction(async (manager) => {
+      for (const allocation of allocations) {
+        await manager.delete(BookingContainerAllocation, {
+          bookingId,
+          containerId: allocation.containerId,
+        });
+        await manager.insert(BookingContainerAllocation, {
+          bookingId,
+          containerId: allocation.containerId,
+          vehicleId: allocation.vehicleId,
+          containerType: 'CONTAINER',
+          quantity: 1,
+        });
+      }
+    });
+
+    return {
+      success: true,
+      allocated: allocations.length,
+    };
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/allocate-containers.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/allocate-containers.dto.ts
new file mode 100644
index 000000000..8b9b7da39
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/dto/allocate-containers.dto.ts
@@ -0,0 +1,8 @@
+export class ContainerAllocationDto {
+  containerId!: string;
+  vehicleId!: string;
+}
+
+export class AllocateContainersDto {
+  allocations!: ContainerAllocationDto[];
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking-container-allocation.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking-container-allocation.entity.ts
new file mode 100644
index 000000000..8cb186e09
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking-container-allocation.entity.ts
@@ -0,0 +1,32 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Booking } from './booking.entity';
+import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+
+@Entity({ schema: 'freight', name: 'booking_container_allocations' })
+@Index(['bookingId'])
+@Index(['vehicleId'])
+export class BookingContainerAllocation extends BaseEntity {
+  @ManyToOne(() => Booking, (b) => b.containerAllocations)
+  @JoinColumn({ name: 'booking_id' })
+  booking!: Booking;
+
+  @Column('uuid', { name: 'booking_id' })
+  bookingId!: string;
+
+  @Column('uuid', { name: 'container_id' })
+  containerId!: string;
+
+  @ManyToOne(() => Vehicle)
+  @JoinColumn({ name: 'vehicle_id' })
+  vehicle!: Vehicle;
+
+  @Column('uuid', { name: 'vehicle_id', nullable: true })
+  vehicleId?: string;
+
+  @Column('text')
+  containerType!: string; // CONTAINER, BULK_DRY, etc
+
+  @Column('integer', { default: 1 })
+  quantity!: number;
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
index ac7fe636a..3c93b26f2 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
@@ -13,6 +13,7 @@ import { FileRecord } from '../../files/entities/file.entity';
 import { BookingApprovalStep } from './booking-approval-step.entity';
 import { BookingCargoModifier } from './booking-cargo-modifier.entity';
 import { BookingContainer } from './booking-container.entity';
+import { BookingContainerAllocation } from './booking-container-allocation.entity';
 import { BookingRateSnapshot } from './booking-rate-snapshot.entity';
 import { BookingReviewNote } from './booking-review-note.entity';
 
@@ -441,6 +442,9 @@ export class Booking extends BaseEntity {
   @OneToMany(() => BookingContainer, (bc) => bc.booking)
   bookingContainers?: BookingContainer[];
 
+  @OneToMany(() => BookingContainerAllocation, (ca) => ca.booking)
+  containerAllocations?: BookingContainerAllocation[];
+
   @OneToMany(() => BookingCargoModifier, (m) => m.booking)
   cargoModifiers?: BookingCargoModifier[];
 
diff --git a/apps/edr-freight-api/src/modules/first-mile/dto/allocate-containers.dto.ts b/apps/edr-freight-api/src/modules/first-mile/dto/allocate-containers.dto.ts
new file mode 100644
index 000000000..b750f1147
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/first-mile/dto/allocate-containers.dto.ts
@@ -0,0 +1,8 @@
+export class FirstMileContainerAllocationDto {
+  containerId!: string;
+  vehicleId!: string;
+}
+
+export class AllocateFirstMileContainersDto {
+  allocations!: FirstMileContainerAllocationDto[];
+}
diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
new file mode 100644
index 000000000..e9407a57f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
@@ -0,0 +1,36 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
+
+import { FirstMile } from './first-mile.entity';
+import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+
+@Entity({ name: 'first_mile_container_allocations', schema: 'freight' })
+@Index(['firstMileId'])
+@Index(['vehicleId'])
+export class FirstMileContainerAllocation extends BaseEntity {
+  @Column({ name: 'first_mile_id', type: 'uuid' })
+  firstMileId!: string;
+
+  @ManyToOne(() => FirstMile, (firstMile) => firstMile.containerAllocations, {
+    nullable: false,
+    eager: false,
+  })
+  @JoinColumn({ name: 'first_mile_id' })
+  firstMile?: FirstMile;
+
+  @Column({ name: 'container_id', type: 'uuid' })
+  containerId!: string;
+
+  @Column({ name: 'vehicle_id', type: 'uuid', nullable: true })
+  vehicleId?: string | null;
+
+  @ManyToOne(() => Vehicle, { nullable: true, eager: false })
+  @JoinColumn({ name: 'vehicle_id' })
+  vehicle?: Vehicle | null;
+
+  @Column({ name: 'container_type', type: 'text' })
+  containerType!: string;
+
+  @Column({ name: 'quantity', type: 'int', default: 1 })
+  quantity!: number;
+}
diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
index e810d23cc..b2eb3801f 100644
--- a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
@@ -1,8 +1,9 @@
 import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 
 import { Booking } from '../../bookings/entities/booking.entity';
 import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+import { FirstMileContainerAllocation } from './first-mile-container-allocation.entity';
 
 export const FIRST_MILE_STATUSES = [
   'PAYMENT_PENDING',
@@ -49,4 +50,11 @@ export class FirstMile extends BaseEntity {
   @ManyToOne(() => Vehicle, { nullable: true, eager: false })
   @JoinColumn({ name: 'vehicle_id' })
   vehicle?: Vehicle | null;
+
+  @OneToMany(
+    () => FirstMileContainerAllocation,
+    (containerAllocation) => containerAllocation.firstMile,
+    { eager: false },
+  )
+  containerAllocations!: FirstMileContainerAllocation[];
 }
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
index 78c3d43ff..3ecc2db20 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
@@ -17,6 +17,7 @@ import { TrainSchedulingManage, TrainSchedulingView } from '../../common/booking
 
 import { CreateFirstMileDto } from './dto/create-first-mile.dto';
 import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
+import { AllocateFirstMileContainersDto } from './dto/allocate-containers.dto';
 import { FirstMileStatus } from './entities/first-mile.entity';
 import { FirstMileService } from './first-mile.service';
 
@@ -83,4 +84,14 @@ export class FirstMileController {
   remove(@Param('id', ParseUUIDPipe) id: string) {
     return this.firstMileService.remove(id);
   }
+
+  @Post(':firstMileId/allocate-containers')
+  @TrainSchedulingManage()
+  @ApiOperation({ summary: 'Allocate containers to vehicles for a first-mile leg' })
+  allocateContainers(
+    @Param('firstMileId', ParseUUIDPipe) firstMileId: string,
+    @Body() dto: AllocateFirstMileContainersDto,
+  ) {
+    return this.firstMileService.allocateContainers(firstMileId, dto.allocations);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
index bf6815af7..0cdf3c92c 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
@@ -6,13 +6,14 @@ import { DriversModule } from '../drivers/drivers.module';
 import { NotificationsModule } from '../notifications/notifications.module';
 import { VehiclesModule } from '../vehicles/vehicles.module';
 import { FirstMile } from './entities/first-mile.entity';
+import { FirstMileContainerAllocation } from './entities/first-mile-container-allocation.entity';
 import { FirstMileController } from './first-mile.controller';
 import { FirstMileRepository } from './first-mile.repository';
 import { FirstMileService } from './first-mile.service';
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([FirstMile]),
+    TypeOrmModule.forFeature([FirstMile, FirstMileContainerAllocation]),
     forwardRef(() => BookingsModule),
     VehiclesModule,
     DriversModule,
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
index 45c2658db..08cd9ab10 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
@@ -1,5 +1,7 @@
 import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { FindOptionsWhere } from 'typeorm';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
 
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { DriversService } from '../drivers/drivers.service';
@@ -8,6 +10,7 @@ import { VehiclesService } from '../vehicles/vehicles.service';
 import { CreateFirstMileDto } from './dto/create-first-mile.dto';
 import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
 import { FirstMile, FirstMileStatus } from './entities/first-mile.entity';
+import { FirstMileContainerAllocation } from './entities/first-mile-container-allocation.entity';
 import { FirstMileRepository } from './first-mile.repository';
 
 type FirstMileListFilter = {
@@ -32,6 +35,7 @@ export class FirstMileService {
   private readonly logger = new Logger(FirstMileService.name);
 
   constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
     private readonly firstMileRepository: FirstMileRepository,
     private readonly bookingsRepository: BookingsRepository,
     private readonly vehiclesService: VehiclesService,
@@ -273,4 +277,35 @@ export class FirstMileService {
     await this.findById(id);
     await this.firstMileRepository.softDelete(id);
   }
+
+  async allocateContainers(
+    firstMileId: string,
+    allocations: Array<{ containerId: string; vehicleId: string }>,
+  ) {
+    const firstMile = await this.findById(firstMileId);
+    if (!firstMile) {
+      throw new NotFoundException(`First-mile record ${firstMileId} not found`);
+    }
+
+    await this.dataSource.transaction(async (manager) => {
+      for (const allocation of allocations) {
+        await manager.delete(FirstMileContainerAllocation, {
+          firstMileId,
+          containerId: allocation.containerId,
+        });
+        await manager.insert(FirstMileContainerAllocation, {
+          firstMileId,
+          containerId: allocation.containerId,
+          vehicleId: allocation.vehicleId,
+          containerType: 'CONTAINER',
+          quantity: 1,
+        });
+      }
+    });
+
+    return {
+      success: true,
+      allocated: allocations.length,
+    };
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/last-mile/dto/allocate-containers.dto.ts b/apps/edr-freight-api/src/modules/last-mile/dto/allocate-containers.dto.ts
new file mode 100644
index 000000000..de86ac883
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/last-mile/dto/allocate-containers.dto.ts
@@ -0,0 +1,8 @@
+export class LastMileContainerAllocationDto {
+  containerId!: string;
+  vehicleId!: string;
+}
+
+export class AllocateLastMileContainersDto {
+  allocations!: LastMileContainerAllocationDto[];
+}
diff --git a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile-container-allocation.entity.ts b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile-container-allocation.entity.ts
new file mode 100644
index 000000000..8a61c73bf
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile-container-allocation.entity.ts
@@ -0,0 +1,32 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { LastMile } from './last-mile.entity';
+import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+
+@Entity({ schema: 'freight', name: 'last_mile_container_allocations' })
+@Index(['lastMileId'])
+@Index(['vehicleId'])
+export class LastMileContainerAllocation extends BaseEntity {
+  @ManyToOne(() => LastMile, (lm) => lm.containerAllocations)
+  @JoinColumn({ name: 'last_mile_id' })
+  lastMile!: LastMile;
+
+  @Column('uuid', { name: 'last_mile_id' })
+  lastMileId!: string;
+
+  @Column('uuid', { name: 'container_id' })
+  containerId!: string;
+
+  @ManyToOne(() => Vehicle)
+  @JoinColumn({ name: 'vehicle_id' })
+  vehicle?: Vehicle | null;
+
+  @Column('uuid', { name: 'vehicle_id', nullable: true })
+  vehicleId?: string | null;
+
+  @Column('text')
+  containerType!: string;
+
+  @Column('integer', { default: 1 })
+  quantity!: number;
+}
diff --git a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
index ad4b789f4..61aad0d72 100644
--- a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
@@ -1,8 +1,9 @@
 import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 
 import { Booking } from '../../bookings/entities/booking.entity';
 import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+import { LastMileContainerAllocation } from './last-mile-container-allocation.entity';
 
 export const LAST_MILE_STATUSES = [
   'PAYMENT_PENDING',
@@ -49,4 +50,7 @@ export class LastMile extends BaseEntity {
   @ManyToOne(() => Vehicle, { nullable: true, eager: false })
   @JoinColumn({ name: 'vehicle_id' })
   vehicle?: Vehicle | null;
+
+  @OneToMany(() => LastMileContainerAllocation, (ca) => ca.lastMile)
+  containerAllocations?: LastMileContainerAllocation[];
 }
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
index e8abf52c6..935aa5ac7 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
@@ -17,6 +17,7 @@ import { TrainSchedulingManage, TrainSchedulingView } from '../../common/booking
 
 import { CreateLastMileDto } from './dto/create-last-mile.dto';
 import { UpdateLastMileDto } from './dto/update-last-mile.dto';
+import { AllocateLastMileContainersDto } from './dto/allocate-containers.dto';
 import { LastMileStatus } from './entities/last-mile.entity';
 import { LastMileService } from './last-mile.service';
 
@@ -83,4 +84,14 @@ export class LastMileController {
   remove(@Param('id', ParseUUIDPipe) id: string) {
     return this.lastMileService.remove(id);
   }
+
+  @Post(':id/allocate-containers')
+  @TrainSchedulingManage()
+  @ApiOperation({ summary: 'Allocate containers to vehicles' })
+  async allocateContainers(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: AllocateLastMileContainersDto,
+  ) {
+    return this.lastMileService.allocateContainers(id, dto.allocations);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
index e4b99a18c..e6ed6634d 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
@@ -6,13 +6,14 @@ import { DriversModule } from '../drivers/drivers.module';
 import { NotificationsModule } from '../notifications/notifications.module';
 import { VehiclesModule } from '../vehicles/vehicles.module';
 import { LastMile } from './entities/last-mile.entity';
+import { LastMileContainerAllocation } from './entities/last-mile-container-allocation.entity';
 import { LastMileController } from './last-mile.controller';
 import { LastMileRepository } from './last-mile.repository';
 import { LastMileService } from './last-mile.service';
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([LastMile]),
+    TypeOrmModule.forFeature([LastMile, LastMileContainerAllocation]),
     forwardRef(() => BookingsModule),
     VehiclesModule,
     DriversModule,
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
index 77a8a2fea..5faad49b9 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
@@ -1,5 +1,5 @@
 import { Injectable, Logger, NotFoundException } from '@nestjs/common';
-import { FindOptionsWhere } from 'typeorm';
+import { DataSource, FindOptionsWhere } from 'typeorm';
 
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { DriversService } from '../drivers/drivers.service';
@@ -8,6 +8,7 @@ import { VehiclesService } from '../vehicles/vehicles.service';
 import { CreateLastMileDto } from './dto/create-last-mile.dto';
 import { UpdateLastMileDto } from './dto/update-last-mile.dto';
 import { LastMile, LastMileStatus } from './entities/last-mile.entity';
+import { LastMileContainerAllocation } from './entities/last-mile-container-allocation.entity';
 import { LastMileRepository } from './last-mile.repository';
 
 type LastMileListFilter = {
@@ -37,6 +38,7 @@ export class LastMileService {
     private readonly vehiclesService: VehiclesService,
     private readonly driversService: DriversService,
     private readonly smsClient: SmsClientService,
+    private readonly dataSource: DataSource,
   ) {}
 
   async acceptBooking(bookingReference: string): Promise<LastMile | null> {
@@ -206,4 +208,35 @@ export class LastMileService {
     await this.findById(id);
     await this.lastMileRepository.softDelete(id);
   }
+
+  async allocateContainers(
+    lastMileId: string,
+    allocations: Array<{ containerId: string; vehicleId: string }>,
+  ) {
+    const lastMile = await this.findById(lastMileId);
+    if (!lastMile) {
+      throw new NotFoundException(`Last-mile record ${lastMileId} not found`);
+    }
+
+    await this.dataSource.transaction(async (manager) => {
+      for (const allocation of allocations) {
+        await manager.delete(LastMileContainerAllocation, {
+          lastMileId,
+          containerId: allocation.containerId,
+        });
+        await manager.insert(LastMileContainerAllocation, {
+          lastMileId,
+          containerId: allocation.containerId,
+          vehicleId: allocation.vehicleId,
+          containerType: 'CONTAINER',
+          quantity: 1,
+        });
+      }
+    });
+
+    return {
+      success: true,
+      allocated: allocations.length,
+    };
+  }
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/ContainerAllocationTable.tsx b/apps/edr-freight-web/backoffice/src/components/ContainerAllocationTable.tsx
new file mode 100644
index 000000000..950cfd476
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/ContainerAllocationTable.tsx
@@ -0,0 +1,164 @@
+import { useState, useMemo } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  Box,
+  Button,
+  Group,
+  Loader,
+  Select,
+  Stack,
+  Table,
+  Text,
+  Alert,
+} from "@mantine/core";
+import { AlertCircle } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { vehiclesService } from "@/services/vehicles.service";
+
+export interface ContainerAllocationRow {
+  id: string;
+  type: string;
+  qty: number;
+}
+
+export interface ContainerAllocationTableProps {
+  bookingId: string;
+  containers: ContainerAllocationRow[];
+  onSave: (allocations: Array<{ containerId: string; vehicleId: string }>) => Promise<void>;
+}
+
+/**
+ * Manual container-to-vehicle allocation table for freight bookings.
+ * Displays containers with type/qty, vehicle dropdown per row, and save action.
+ */
+export function ContainerAllocationTable({
+  bookingId,
+  containers,
+  onSave,
+}: ContainerAllocationTableProps) {
+  const [allocations, setAllocations] = useState<Record<string, string | null>>(
+    () => containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+  );
+
+  const { data: vehicles = [], isLoading: vehiclesLoading } = useQuery({
+    queryKey: ["vehicles", "active"],
+    queryFn: () => vehiclesService.getAll({ status: "ACTIVE" }),
+  });
+
+  const vehicleOptions = useMemo(
+    () =>
+      vehicles.map((v) => ({
+        value: v.id,
+        label: `${v.plateNumber} (${v.vehicleType})`,
+        description: `${v.model} · ${v.manufacturer}`,
+      })),
+    [vehicles],
+  );
+
+  const saveAllocation = useMutation({
+    mutationFn: async () => {
+      const mappings = containers
+        .filter((c) => allocations[c.id])
+        .map((c) => ({
+          containerId: c.id,
+          vehicleId: allocations[c.id]!,
+        }));
+
+      if (mappings.length === 0) {
+        throw new Error("No containers allocated to vehicles");
+      }
+
+      await onSave(mappings);
+    },
+    onSuccess: () => {
+      toast.success("Container allocations saved");
+      setAllocations(
+        containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+      );
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to save allocations",
+      );
+    },
+  });
+
+  const allocatedCount = Object.values(allocations).filter(Boolean).length;
+  const allAllocated = allocatedCount === containers.length;
+
+  if (vehiclesLoading) {
+    return (
+      <Box display="flex" justifyContent="center" p="xl">
+        <Loader size="sm" />
+      </Box>
+    );
+  }
+
+  return (
+    <Stack gap="md">
+      {vehicles.length === 0 && (
+        <Alert icon={<AlertCircle size={16} />} color="yellow">
+          No active vehicles available. Add vehicles before allocating containers.
+        </Alert>
+      )}
+
+      <Box style={{ overflowX: "auto" }}>
+        <Table verticalSpacing="md" horizontalSpacing="md" highlightOnHover>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Container ID</Table.Th>
+              <Table.Th>Type</Table.Th>
+              <Table.Th>Qty</Table.Th>
+              <Table.Th>Assigned Vehicle</Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {containers.map((container) => (
+              <Table.Tr key={container.id}>
+                <Table.Td>
+                  <Text fw={600} size="sm">
+                    {container.id}
+                  </Text>
+                </Table.Td>
+                <Table.Td>{container.type}</Table.Td>
+                <Table.Td>{container.qty}</Table.Td>
+                <Table.Td>
+                  <Select
+                    placeholder="Select vehicle"
+                    data={vehicleOptions}
+                    value={allocations[container.id] ?? null}
+                    onChange={(value) =>
+                      setAllocations((prev) => ({
+                        ...prev,
+                        [container.id]: value,
+                      }))
+                    }
+                    searchable
+                    clearable
+                    disabled={vehicles.length === 0}
+                    style={{ minWidth: 200 }}
+                  />
+                </Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Box>
+
+      <Group justify="space-between">
+        <Text size="sm" c="dimmed">
+          {allocatedCount} of {containers.length} containers allocated
+        </Text>
+        <Button
+          color="edr-green"
+          loading={saveAllocation.isPending}
+          disabled={allocatedCount === 0 || vehicles.length === 0}
+          onClick={() => saveAllocation.mutate()}
+        >
+          Save Allocations
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/FirstMileContainerAllocationTable.tsx b/apps/edr-freight-web/backoffice/src/components/FirstMileContainerAllocationTable.tsx
new file mode 100644
index 000000000..85bba1dc4
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/FirstMileContainerAllocationTable.tsx
@@ -0,0 +1,164 @@
+import { useState, useMemo } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  Box,
+  Button,
+  Group,
+  Loader,
+  Select,
+  Stack,
+  Table,
+  Text,
+  Alert,
+} from "@mantine/core";
+import { AlertCircle } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { vehiclesService } from "@/services/vehicles.service";
+
+export interface ContainerAllocationRow {
+  id: string;
+  type: string;
+  qty: number;
+}
+
+export interface FirstMileContainerAllocationTableProps {
+  firstMileId: string;
+  containers: ContainerAllocationRow[];
+  onSave: (allocations: Array<{ containerId: string; vehicleId: string }>) => Promise<void>;
+}
+
+/**
+ * Manual container-to-vehicle allocation table for first-mile pickups.
+ * Displays containers with type/qty, vehicle dropdown per row, and save action.
+ */
+export function FirstMileContainerAllocationTable({
+  firstMileId,
+  containers,
+  onSave,
+}: FirstMileContainerAllocationTableProps) {
+  const [allocations, setAllocations] = useState<Record<string, string | null>>(
+    () => containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+  );
+
+  const { data: vehicles = [], isLoading: vehiclesLoading } = useQuery({
+    queryKey: ["vehicles", "active"],
+    queryFn: () => vehiclesService.getAll({ status: "ACTIVE" }),
+  });
+
+  const vehicleOptions = useMemo(
+    () =>
+      vehicles.map((v) => ({
+        value: v.id,
+        label: `${v.plateNumber} (${v.vehicleType})`,
+        description: `${v.model} · ${v.manufacturer}`,
+      })),
+    [vehicles],
+  );
+
+  const saveAllocation = useMutation({
+    mutationFn: async () => {
+      const mappings = containers
+        .filter((c) => allocations[c.id])
+        .map((c) => ({
+          containerId: c.id,
+          vehicleId: allocations[c.id]!,
+        }));
+
+      if (mappings.length === 0) {
+        throw new Error("No containers allocated to vehicles");
+      }
+
+      await onSave(mappings);
+    },
+    onSuccess: () => {
+      toast.success("Container allocations saved");
+      setAllocations(
+        containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+      );
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to save allocations",
+      );
+    },
+  });
+
+  const allocatedCount = Object.values(allocations).filter(Boolean).length;
+  const allAllocated = allocatedCount === containers.length;
+
+  if (vehiclesLoading) {
+    return (
+      <Box display="flex" justifyContent="center" p="xl">
+        <Loader size="sm" />
+      </Box>
+    );
+  }
+
+  return (
+    <Stack gap="md">
+      {vehicles.length === 0 && (
+        <Alert icon={<AlertCircle size={16} />} color="yellow">
+          No active vehicles available. Add vehicles before allocating containers.
+        </Alert>
+      )}
+
+      <Box style={{ overflowX: "auto" }}>
+        <Table verticalSpacing="md" horizontalSpacing="md" highlightOnHover>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Container ID</Table.Th>
+              <Table.Th>Type</Table.Th>
+              <Table.Th>Qty</Table.Th>
+              <Table.Th>Assigned Vehicle</Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {containers.map((container) => (
+              <Table.Tr key={container.id}>
+                <Table.Td>
+                  <Text fw={600} size="sm">
+                    {container.id}
+                  </Text>
+                </Table.Td>
+                <Table.Td>{container.type}</Table.Td>
+                <Table.Td>{container.qty}</Table.Td>
+                <Table.Td>
+                  <Select
+                    placeholder="Select vehicle"
+                    data={vehicleOptions}
+                    value={allocations[container.id] ?? null}
+                    onChange={(value) =>
+                      setAllocations((prev) => ({
+                        ...prev,
+                        [container.id]: value,
+                      }))
+                    }
+                    searchable
+                    clearable
+                    disabled={vehicles.length === 0}
+                    style={{ minWidth: 200 }}
+                  />
+                </Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Box>
+
+      <Group justify="space-between">
+        <Text size="sm" c="dimmed">
+          {allocatedCount} of {containers.length} containers allocated
+        </Text>
+        <Button
+          color="edr-green"
+          loading={saveAllocation.isPending}
+          disabled={allocatedCount === 0 || vehicles.length === 0}
+          onClick={() => saveAllocation.mutate()}
+        >
+          Save Allocations
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/LastMileContainerAllocationTable.tsx b/apps/edr-freight-web/backoffice/src/components/LastMileContainerAllocationTable.tsx
new file mode 100644
index 000000000..d11d99a4a
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/LastMileContainerAllocationTable.tsx
@@ -0,0 +1,164 @@
+import { useState, useMemo } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  Box,
+  Button,
+  Group,
+  Loader,
+  Select,
+  Stack,
+  Table,
+  Text,
+  Alert,
+} from "@mantine/core";
+import { AlertCircle } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { vehiclesService } from "@/services/vehicles.service";
+
+export interface LastMileContainerRow {
+  id: string;
+  type: string;
+  qty: number;
+}
+
+export interface LastMileContainerAllocationTableProps {
+  lastMileId: string;
+  containers: LastMileContainerRow[];
+  onSave: (allocations: Array<{ containerId: string; vehicleId: string }>) => Promise<void>;
+}
+
+/**
+ * Manual container-to-vehicle allocation table for last-mile deliveries.
+ * Displays containers with type/qty, vehicle dropdown per row, and save action.
+ */
+export function LastMileContainerAllocationTable({
+  lastMileId,
+  containers,
+  onSave,
+}: LastMileContainerAllocationTableProps) {
+  const [allocations, setAllocations] = useState<Record<string, string | null>>(
+    () => containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+  );
+
+  const { data: vehicles = [], isLoading: vehiclesLoading } = useQuery({
+    queryKey: ["vehicles", "active"],
+    queryFn: () => vehiclesService.getAll({ status: "ACTIVE" }),
+  });
+
+  const vehicleOptions = useMemo(
+    () =>
+      vehicles.map((v) => ({
+        value: v.id,
+        label: `${v.plateNumber} (${v.vehicleType})`,
+        description: `${v.model} · ${v.manufacturer}`,
+      })),
+    [vehicles],
+  );
+
+  const saveAllocation = useMutation({
+    mutationFn: async () => {
+      const mappings = containers
+        .filter((c) => allocations[c.id])
+        .map((c) => ({
+          containerId: c.id,
+          vehicleId: allocations[c.id]!,
+        }));
+
+      if (mappings.length === 0) {
+        throw new Error("No containers allocated to vehicles");
+      }
+
+      await onSave(mappings);
+    },
+    onSuccess: () => {
+      toast.success("Container allocations saved");
+      setAllocations(
+        containers.reduce((acc, c) => ({ ...acc, [c.id]: null }), {}),
+      );
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to save allocations",
+      );
+    },
+  });
+
+  const allocatedCount = Object.values(allocations).filter(Boolean).length;
+  const allAllocated = allocatedCount === containers.length;
+
+  if (vehiclesLoading) {
+    return (
+      <Box display="flex" justifyContent="center" p="xl">
+        <Loader size="sm" />
+      </Box>
+    );
+  }
+
+  return (
+    <Stack gap="md">
+      {vehicles.length === 0 && (
+        <Alert icon={<AlertCircle size={16} />} color="yellow">
+          No active vehicles available. Add vehicles before allocating containers.
+        </Alert>
+      )}
+
+      <Box style={{ overflowX: "auto" }}>
+        <Table verticalSpacing="md" horizontalSpacing="md" highlightOnHover>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Container ID</Table.Th>
+              <Table.Th>Type</Table.Th>
+              <Table.Th>Qty</Table.Th>
+              <Table.Th>Assigned Vehicle</Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {containers.map((container) => (
+              <Table.Tr key={container.id}>
+                <Table.Td>
+                  <Text fw={600} size="sm">
+                    {container.id}
+                  </Text>
+                </Table.Td>
+                <Table.Td>{container.type}</Table.Td>
+                <Table.Td>{container.qty}</Table.Td>
+                <Table.Td>
+                  <Select
+                    placeholder="Select vehicle"
+                    data={vehicleOptions}
+                    value={allocations[container.id] ?? null}
+                    onChange={(value) =>
+                      setAllocations((prev) => ({
+                        ...prev,
+                        [container.id]: value,
+                      }))
+                    }
+                    searchable
+                    clearable
+                    disabled={vehicles.length === 0}
+                    style={{ minWidth: 200 }}
+                  />
+                </Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Box>
+
+      <Group justify="space-between">
+        <Text size="sm" c="dimmed">
+          {allocatedCount} of {containers.length} containers allocated
+        </Text>
+        <Button
+          color="edr-green"
+          loading={saveAllocation.isPending}
+          disabled={allocatedCount === 0 || vehicles.length === 0}
+          onClick={() => saveAllocation.mutate()}
+        >
+          Save Allocations
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index 1217b8762..7a7604cc7 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,6 +1,6 @@
-export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+// export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
 
-// export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingDetailPage.tsx
index 4ecfeebd5..bf01c4818 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingDetailPage.tsx
@@ -1,5 +1,7 @@
 import { Container, Grid, Stack } from "@mantine/core";
 import { useNavigate, useParams } from "react-router-dom";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import toast from "react-hot-toast";
 
 import {
   BookingApprovalCard,
@@ -16,10 +18,26 @@ import {
   type BookingDetailView,
 } from "@/components/bookings/detail";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
+import ContainerAllocationTable from "@/components/ContainerAllocationTable";
+import { api } from "@/services/api";
+import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 
 const BookingDetailPage = () => {
   const { id } = useParams<{ id: string }>();
   const navigate = useNavigate();
+  const qc = useQueryClient();
+
+  const allocateMutation = useMutation({
+    mutationFn: (data: any) =>
+      api.post(`/bookings/${id}/allocate-containers`, data),
+    onSuccess: () => {
+      toast.success("Containers allocated");
+      qc.invalidateQueries({ queryKey: QUERY_KEYS.BOOKINGS.byId(id ?? "") });
+    },
+    onError: () => {
+      toast.error("Failed to allocate containers");
+    },
+  });
 
   // Mock data - replace with actual API call
   const booking: BookingDetailView = {
@@ -134,6 +152,17 @@ const BookingDetailPage = () => {
               <BookingContainersCard
                 containers={booking.bookingContainers ?? []}
               />
+              <ContainerAllocationTable
+                bookingId={booking.id}
+                containers={(booking.bookingContainers ?? []).map((c) => ({
+                  id: c.id,
+                  type: c.containerType?.label ?? "Unknown",
+                  qty: c.quantity,
+                }))}
+                onSave={(allocations) =>
+                  allocateMutation.mutateAsync({ allocations })
+                }
+              />
               <BookingApprovalCard
                 steps={approvalSteps}
                 approvedCount={approvedCount}
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
index e17ea46c7..59cd50a21 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
@@ -30,9 +30,11 @@ import {
   Text,
   TextInput,
   UnstyledButton,
+  Alert,
 } from "@mantine/core";
 
 import { ruleEngineTable } from "@/components/ruleEngine/ruleEngineStyles";
+import { FirstMileContainerAllocationTable } from "@/components/FirstMileContainerAllocationTable";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { useToast } from "@/hooks/use-toast";
 import {
@@ -44,6 +46,7 @@ import {
 import { bookingsService } from "@/services/bookings.service";
 import { vehiclesService } from "@/services/vehicles.service";
 import { ratesService } from "@/services/rates.service";
+import { apiClient } from "@/services/api-client";
 import type { BookingDetail } from "@/types/booking";
 
 const formatPrice = (amount: number) =>
@@ -336,6 +339,9 @@ const FirstMilePage = () => {
   const [invoiceOpen, setInvoiceOpen] = useState(false);
   const [invoiceRecord, setInvoiceRecord] = useState<FirstMileRecord | null>(null);
 
+  const [containerAllocationOpen, setContainerAllocationOpen] = useState(false);
+  const [containerAllocationFirstMileId, setContainerAllocationFirstMileId] = useState<string | null>(null);
+
   const { data: listData, isLoading } = useQuery({
     queryKey: QUERY_KEYS.FIRST_MILE.list(),
     queryFn: async () => {
@@ -434,6 +440,19 @@ const FirstMilePage = () => {
     },
   });
 
+  const allocateMutation = useMutation({
+    mutationFn: (data) => apiClient.post(`/first-mile/${containerAllocationFirstMileId}/allocate-containers`, data),
+    onSuccess: () => {
+      toast({ title: "Containers allocated" });
+      void qc.invalidateQueries({ queryKey: QUERY_KEYS.FIRST_MILE.detail(containerAllocationFirstMileId ?? "") });
+      setContainerAllocationOpen(false);
+      setContainerAllocationFirstMileId(null);
+    },
+    onError: () => {
+      toast({ title: "Allocation failed", variant: "destructive" });
+    },
+  });
+
   const activeRecord = useMemo(
     () => records.find((r) => r.id === activeId) ?? null,
     [records, activeId],
@@ -508,6 +527,16 @@ const FirstMilePage = () => {
     setInvoiceRecord(null);
   };
 
+  const openContainerAllocation = (firstMileId: string) => {
+    setContainerAllocationFirstMileId(firstMileId);
+    setContainerAllocationOpen(true);
+  };
+
+  const closeContainerAllocation = () => {
+    setContainerAllocationOpen(false);
+    setContainerAllocationFirstMileId(null);
+  };
+
   const handleSaveDistance = () => {
     const distance = parseFloat(distanceValue);
     if (!activeId || isNaN(distance) || distance < 0) {
@@ -1272,6 +1301,56 @@ const FirstMilePage = () => {
           </Group>
         </Stack>
       </Modal>
+
+      {/* Container Allocation modal */}
+      <Modal
+        opened={containerAllocationOpen}
+        onClose={closeContainerAllocation}
+        title={<Text fw={600}>Allocate Containers to Vehicles</Text>}
+        size="xl"
+        radius="lg"
+        centered
+      >
+        <Stack gap="md">
+          {activeRecord && (
+            <>
+              {/* Capacity guidance */}
+              {activeRecord.booking?.cargoType?.label === "BULK" ? (
+                <Alert color="blue" title="Bulk Cargo Allocation">
+                  <Text size="sm">
+                    Select multiple containers per vehicle based on capacity. Each vehicle can carry multiple containers if capacity allows.
+                  </Text>
+                  <Text size="xs" c="dimmed" mt="xs">
+                    Capacity: TBD — TODO: add vehicle capacity_tons to vehicle API if missing
+                  </Text>
+                </Alert>
+              ) : (
+                <Alert color="blue">
+                  <Text size="sm">
+                    One vehicle per container. Each container will be assigned to a single vehicle.
+                  </Text>
+                </Alert>
+              )}
+              <Divider />
+
+              {/* Container table */}
+              <FirstMileContainerAllocationTable
+                firstMileId={activeRecord.id}
+                containers={[
+                  // TODO: Get containers from booking/first-mile data
+                  // For now placeholder with TODO comment
+                ]}
+                onSave={async (allocations) => {
+                  await allocateMutation.mutateAsync(allocations);
+                }}
+              />
+            </>
+          )}
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={closeContainerAllocation}>Close</Button>
+          </Group>
+        </Stack>
+      </Modal>
     </Stack>
   );
 };
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
index 9798a90bf..99a323a6d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
@@ -45,6 +45,8 @@ import {
 } from "@/services/last-mile.service";
 import { vehiclesService } from "@/services/vehicles.service";
 import { ratesService } from "@/services/rates.service";
+import { LastMileContainerAllocationTable, type LastMileContainerRow } from "@/components/LastMileContainerAllocationTable";
+import { api } from "@/auth/http";
 
 const formatPrice = (amount: number) =>
   `ETB ${amount.toLocaleString("en-US", {
@@ -321,6 +323,9 @@ const LastMilePage = () => {
   const [invoiceOpen, setInvoiceOpen] = useState(false);
   const [invoiceRecord, setInvoiceRecord] = useState<LastMileRecord | null>(null);
 
+  const [allocationOpen, setAllocationOpen] = useState(false);
+  const [allocationContainers, setAllocationContainers] = useState<LastMileContainerRow[]>([]);
+
   const { data: listData, isLoading } = useQuery({
     queryKey: QUERY_KEYS.LAST_MILE.list(),
     queryFn: async () => {
@@ -385,6 +390,19 @@ const LastMilePage = () => {
     },
   });
 
+  const allocateMutation = useMutation({
+    mutationFn: (data: Array<{ containerId: string; vehicleId: string }>) =>
+      api.post(`/last-mile/${activeId}/allocate-containers`, data),
+    onSuccess: () => {
+      toast({ title: "Containers allocated", variant: "default" });
+      void qc.invalidateQueries({ queryKey: QUERY_KEYS.LAST_MILE.detail(activeId ?? "") });
+      closeAllocation();
+    },
+    onError: () => {
+      toast({ title: "Allocation failed", variant: "destructive" });
+    },
+  });
+
   const { data: arrivalQueueData, isLoading: arrivalLoading } = useQuery({
     queryKey: ["warehouse-inventory", "arrival-queue"],
     queryFn: () => warehouseService.arrivalQueue().then((r) => r.data),
@@ -477,6 +495,18 @@ const LastMilePage = () => {
     setInvoiceRecord(null);
   };
 
+  const openAllocation = (id: string, containers?: LastMileContainerRow[]) => {
+    setActiveId(id);
+    setAllocationContainers(containers ?? []);
+    setAllocationOpen(true);
+  };
+
+  const closeAllocation = () => {
+    setAllocationOpen(false);
+    setActiveId(null);
+    setAllocationContainers([]);
+  };
+
   const handleSaveDistance = () => {
     const distance = parseFloat(distanceValue);
     if (!activeId || isNaN(distance) || distance < 0) {
@@ -1243,6 +1273,76 @@ const LastMilePage = () => {
           </Group>
         </Stack>
       </Modal>
+
+      {/* Container Allocation modal */}
+      <Modal
+        opened={allocationOpen}
+        onClose={closeAllocation}
+        title={<Text fw={600}>Allocate Containers to Vehicles</Text>}
+        size="xl"
+        radius="lg"
+        centered
+      >
+        <Stack gap="md">
+          {activeRecord && (
+            <>
+              <Card withBorder padding="md" radius="md" bg="var(--mantine-color-gray-0)">
+                <Stack gap="sm">
+                  <Group justify="space-between">
+                    <Stack gap={0}>
+                      <Text fw={600} size="sm">{bookingRef(activeRecord)}</Text>
+                      <Text size="xs" c="dimmed">{customerName(activeRecord)}</Text>
+                    </Stack>
+                    <Stack gap={0} align="flex-end">
+                      <Text size="xs" c="dimmed" tt="uppercase">Cargo Type</Text>
+                      <Text size="sm" fw={600}>{activeRecord.booking?.cargoType?.label ?? activeRecord.booking?.cargoType?.name ?? "—"}</Text>
+                    </Stack>
+                  </Group>
+                </Stack>
+              </Card>
+
+              {/* Capacity logic based on cargo type */}
+              {activeRecord.booking?.cargoType?.name === "BULK" ? (
+                <Card withBorder padding="md" radius="md" bg="var(--mantine-color-blue-0)" style={{ borderColor: "var(--mantine-color-blue-3)" }}>
+                  <Stack gap="sm">
+                    <Group gap="xs">
+                      <Text fw={600} size="sm">Smart Capacity Allocation</Text>
+                    </Group>
+                    <Stack gap={2}>
+                      <Text size="sm">Capacity: TBD</Text>
+                      <Text size="xs" c="dimmed">
+                        TODO: add vehicle capacity_tons to vehicle API if missing
+                      </Text>
+                      <Text size="xs" c="dimmed">
+                        TODO: add container weight to booking if missing
+                      </Text>
+                    </Stack>
+                    <Text size="sm" fw={500} mt="xs">
+                      Select multiple containers per vehicle based on capacity
+                    </Text>
+                  </Stack>
+                </Card>
+              ) : (
+                <Card withBorder padding="md" radius="md" bg="var(--mantine-color-gray-0)">
+                  <Text size="sm" fw={500}>One vehicle per container</Text>
+                </Card>
+              )}
+            </>
+          )}
+
+          <LastMileContainerAllocationTable
+            lastMileId={activeId ?? ""}
+            containers={allocationContainers}
+            onSave={async (mappings) => {
+              await allocateMutation.mutateAsync(mappings);
+            }}
+          />
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={closeAllocation}>Close</Button>
+          </Group>
+        </Stack>
+      </Modal>
     </Stack>
   );
 };

From c728b249c283259eed15d2871dfe264adc641e2e Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 14:48:47 +0000
Subject: [PATCH 25/63] fix

---
 .../entities/first-mile-container-allocation.entity.ts          | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
index e9407a57f..b0fa54c32 100644
--- a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts
@@ -1,5 +1,5 @@
 import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
 
 import { FirstMile } from './first-mile.entity';
 import { Vehicle } from '../../vehicles/entities/vehicle.entity';

From 9b11eeb623925019cf1c19f7bf0f580800e80c31 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 14:54:34 +0000
Subject: [PATCH 26/63] fix

---
 .../backoffice/src/pages/operations/FirstMilePage.tsx           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
index 59cd50a21..06487d3ca 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
@@ -46,7 +46,7 @@ import {
 import { bookingsService } from "@/services/bookings.service";
 import { vehiclesService } from "@/services/vehicles.service";
 import { ratesService } from "@/services/rates.service";
-import { apiClient } from "@/services/api-client";
+import { api } from "@/auth/http";
 import type { BookingDetail } from "@/types/booking";
 
 const formatPrice = (amount: number) =>

From 04bc9eded685b48715bef83ca718face42b64b2f Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 15:28:04 +0000
Subject: [PATCH 27/63] fix

---
 .../src/modules/bookings/bookings.module.ts   |   1 -
 .../first-mile/first-mile-invoice.service.ts  | 106 ++++++++++++++++++
 .../first-mile/first-mile.controller.ts       |  15 ++-
 .../modules/first-mile/first-mile.module.ts   |   7 +-
 .../last-mile/last-mile-invoice.service.ts    |  97 ++++++++++++++++
 .../modules/last-mile/last-mile.controller.ts |  15 ++-
 .../src/modules/last-mile/last-mile.module.ts |   7 +-
 7 files changed, 237 insertions(+), 11 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/first-mile/first-mile-invoice.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/last-mile/last-mile-invoice.service.ts

diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 0d5c52ee0..5d7e3b2c9 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -20,7 +20,6 @@ import { BookingPricingService } from './booking-pricing.service';
 import { BookingReferenceDataService } from './booking-reference-data.service';
 import { BookingTransitionService } from './booking-transition.service';
 import { BookingsController } from './bookings.controller';
-import { BookingAllocationController } from './booking-allocation.controller';
 import { PayController } from './pay.controller';
 import { BookingsRepository } from './bookings.repository';
 import { ConsolidationService } from './consolidation.service';
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile-invoice.service.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile-invoice.service.ts
new file mode 100644
index 000000000..c63a4c9e1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile-invoice.service.ts
@@ -0,0 +1,106 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Freight } from '@edr/types';
+
+import {
+  BillingService,
+  InvoiceEventPayload,
+} from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { FirstMileRepository } from './first-mile.repository';
+import { FirstMile } from './entities/first-mile.entity';
+
+/**
+ * Owns the first-mile ⇄ invoice mapping — the one place that knows how a
+ * first-mile record turns into invoices, which type to use, and how it
+ * advances when paid. First-mile records are billable entities, so they
+ * generate their own invoices directly via {@link BillingService}.
+ */
+@Injectable()
+export class FirstMileInvoiceService {
+  private readonly logger = new Logger(FirstMileInvoiceService.name);
+
+  constructor(
+    private readonly billing: BillingService,
+    private readonly firstMileRepo: FirstMileRepository,
+  ) {}
+
+  /**
+   * Ensure the first-mile record has its invoice, generating one from the
+   * remaining payment if absent. Called when a first-mile record reaches a
+   * billable state. Idempotent — returns the existing open invoice instead
+   * of a duplicate. Returns `null` (and logs) when the record is not billable:
+   * no company to bill.
+   */
+  async ensureInvoiceFor(record: FirstMile): Promise<Invoice | null> {
+    const existing = await this.billing.findPayable(
+      'first_mile' as Freight.InvoiceSource,
+      record.id,
+      'DELIVERY_FEE',
+    );
+    if (existing) return existing;
+
+    if (!record.bookingId) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no booking to reference.`,
+      );
+      return null;
+    }
+
+    // Fetch the booking to get the companyId and companyProfileId
+    const fm = record.booking ? record : (await this.firstMileRepo.findById(record.bookingId, { relations: { booking: true } }));
+    if (!fm) return null;
+    if (!fm.booking?.companyId) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no company to bill.`,
+      );
+      return null;
+    }
+
+    const totalAmount = record.remainingPayment || 0;
+    if (!Number.isFinite(totalAmount) || totalAmount <= 0) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no remaining payment.`,
+      );
+      return null;
+    }
+
+    return this.billing.generateInvoice({
+      source: 'first_mile' as Freight.InvoiceSource,
+      sourceId: record.id,
+      type: 'DELIVERY_FEE',
+      companyId: fm.booking!.companyId,
+      companyProfileId: fm.booking!.companyProfileId || '',
+      currency: 'ETB',
+      lines: [
+        {
+          chargeType: 'DELIVERY',
+          description: 'First-mile delivery',
+          quantity: 1,
+          unitRate: totalAmount,
+          amount: totalAmount,
+        },
+      ],
+      totalAmount,
+    });
+  }
+
+  /**
+   * React to a first-mile invoice being paid — the settlement branch point.
+   * Mark the first-mile record as having completed post-payment processing.
+   */
+  @OnEvent('first_mile.invoice.paid')
+  async onPaid(payload: InvoiceEventPayload): Promise<void> {
+    if (payload.type === 'DELIVERY_FEE') {
+      const record = await this.firstMileRepo.findById(payload.sourceId);
+      if (!record) {
+        this.logger.warn(
+          `Cannot mark unknown first-mile record ${payload.sourceId} as paid.`,
+        );
+        return;
+      }
+
+      this.logger.log(`First-mile invoice paid for record ${payload.sourceId}.`);
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
index 3ecc2db20..6bb307a4b 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts
@@ -20,13 +20,17 @@ import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
 import { AllocateFirstMileContainersDto } from './dto/allocate-containers.dto';
 import { FirstMileStatus } from './entities/first-mile.entity';
 import { FirstMileService } from './first-mile.service';
+import { FirstMileInvoiceService } from './first-mile-invoice.service';
 
 @ApiTags('first-mile')
 @ApiBearerAuth()
 @Controller('first-mile')
 @TrainSchedulingView()
 export class FirstMileController {
-  constructor(private readonly firstMileService: FirstMileService) {}
+  constructor(
+    private readonly firstMileService: FirstMileService,
+    private readonly firstMileInvoiceService: FirstMileInvoiceService,
+  ) {}
 
   @Get()
   @ApiOperation({ summary: 'List first-mile legs' })
@@ -73,8 +77,13 @@ export class FirstMileController {
   @Patch(':id')
   @TrainSchedulingManage()
   @ApiOperation({ summary: 'Update a first-mile leg' })
-  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateFirstMileDto) {
-    return this.firstMileService.update(id, dto);
+  async update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateFirstMileDto) {
+    const record = await this.firstMileService.update(id, dto);
+    // Auto-generate invoice if distance or payment was updated
+    if (dto.exactKm !== undefined || dto.remainingPayment !== undefined) {
+      await this.firstMileInvoiceService.ensureInvoiceFor(record);
+    }
+    return record;
   }
 
   @Delete(':id')
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
index 0cdf3c92c..a69c920f1 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts
@@ -1,6 +1,7 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { BillingModule } from '../billing/billing.module';
 import { BookingsModule } from '../bookings/bookings.module';
 import { DriversModule } from '../drivers/drivers.module';
 import { NotificationsModule } from '../notifications/notifications.module';
@@ -8,19 +9,21 @@ import { VehiclesModule } from '../vehicles/vehicles.module';
 import { FirstMile } from './entities/first-mile.entity';
 import { FirstMileContainerAllocation } from './entities/first-mile-container-allocation.entity';
 import { FirstMileController } from './first-mile.controller';
+import { FirstMileInvoiceService } from './first-mile-invoice.service';
 import { FirstMileRepository } from './first-mile.repository';
 import { FirstMileService } from './first-mile.service';
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([FirstMile, FirstMileContainerAllocation]),
+    BillingModule,
     forwardRef(() => BookingsModule),
     VehiclesModule,
     DriversModule,
     NotificationsModule,
   ],
   controllers: [FirstMileController],
-  providers: [FirstMileRepository, FirstMileService],
-  exports: [FirstMileRepository, FirstMileService],
+  providers: [FirstMileRepository, FirstMileService, FirstMileInvoiceService],
+  exports: [FirstMileRepository, FirstMileService, FirstMileInvoiceService],
 })
 export class FirstMileModule {}
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile-invoice.service.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile-invoice.service.ts
new file mode 100644
index 000000000..c304a89e8
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile-invoice.service.ts
@@ -0,0 +1,97 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Freight } from '@edr/types';
+
+import {
+  BillingService,
+  GenerateInvoiceInput,
+  InvoiceEventPayload,
+} from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { LastMileRepository } from './last-mile.repository';
+import { LastMile } from './entities/last-mile.entity';
+
+/**
+ * Owns the last-mile ⇄ invoice mapping — the one place that knows how a last-mile
+ * record turns into invoices, which type to use, and how it advances when paid.
+ * Last-mile records are billable business entities for delivery fees, so they
+ * generate their own invoices directly via {@link BillingService}. All last-mile-specific
+ * type branching lives here, at the two points it belongs: invoice creation and
+ * settlement (the paid handler).
+ */
+@Injectable()
+export class LastMileInvoiceService {
+  private readonly logger = new Logger(LastMileInvoiceService.name);
+
+  constructor(
+    private readonly billing: BillingService,
+    private readonly lastMileRepo: LastMileRepository,
+  ) {}
+
+  /**
+   * Ensure the last-mile record has its invoice, generating one from the
+   * remainingPayment if absent. Called when a last-mile record reaches a
+   * billable state. Idempotent — returns the existing open invoice instead
+   * of a duplicate. Returns `null` (and logs) when the record is not billable:
+   * no company to bill (invoices FK requires a companyId).
+   */
+  async ensureInvoiceFor(record: LastMile): Promise<Invoice | null> {
+    // Check if invoice already exists
+    const existing = await this.billing.findPayable(
+      'last_mile' as Freight.InvoiceSource,
+      record.id,
+      'DELIVERY_FEE',
+    );
+    if (existing) return existing;
+
+    // Can't bill without company
+    const lm = record.booking ? record : (await this.lastMileRepo.findById(record.id, { relations: { booking: true } }));
+    if (!lm) return null;
+    if (!lm.booking?.companyId) {
+      this.logger.warn(
+        `Skipping invoice for last-mile record ${record.id}: no company to bill.`,
+      );
+      return null;
+    }
+
+    // Generate invoice with remainingPayment as totalAmount
+    const input: GenerateInvoiceInput = {
+      source: 'last_mile' as Freight.InvoiceSource,
+      sourceId: record.id,
+      type: 'DELIVERY_FEE',
+      companyId: lm.booking!.companyId,
+      companyProfileId: lm.booking!.companyProfileId || '',
+      currency: 'ETB',
+      lines: [
+        {
+          chargeType: 'DELIVERY',
+          description: 'Last-mile delivery',
+          quantity: 1,
+          unitRate: record.remainingPayment || 0,
+          amount: record.remainingPayment || 0,
+        },
+      ],
+      totalAmount: record.remainingPayment || 0,
+    };
+
+    return this.billing.generateInvoice(input);
+  }
+
+  /**
+   * React to a last-mile invoice being paid — the settlement branch point.
+   * Advances the last-mile record to mark post-payment as completed.
+   */
+  @OnEvent('last_mile.invoice.paid')
+  async onPaid(payload: InvoiceEventPayload): Promise<void> {
+    if (payload.type === 'DELIVERY_FEE') {
+      const record = await this.lastMileRepo.findById(payload.sourceId);
+      if (record) {
+        this.logger.log(`Last-mile invoice paid for record ${payload.sourceId}.`);
+      } else {
+        this.logger.warn(
+          `Cannot mark last-mile record ${payload.sourceId} as paid: not found.`,
+        );
+      }
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
index 935aa5ac7..929d97a3e 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
@@ -20,13 +20,17 @@ import { UpdateLastMileDto } from './dto/update-last-mile.dto';
 import { AllocateLastMileContainersDto } from './dto/allocate-containers.dto';
 import { LastMileStatus } from './entities/last-mile.entity';
 import { LastMileService } from './last-mile.service';
+import { LastMileInvoiceService } from './last-mile-invoice.service';
 
 @ApiTags('last-mile')
 @ApiBearerAuth()
 @Controller('last-mile')
 @TrainSchedulingView()
 export class LastMileController {
-  constructor(private readonly lastMileService: LastMileService) {}
+  constructor(
+    private readonly lastMileService: LastMileService,
+    private readonly lastMileInvoiceService: LastMileInvoiceService,
+  ) {}
 
   @Get()
   @ApiOperation({ summary: 'List last-mile legs' })
@@ -73,8 +77,13 @@ export class LastMileController {
   @Patch(':id')
   @TrainSchedulingManage()
   @ApiOperation({ summary: 'Update a last-mile leg' })
-  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateLastMileDto) {
-    return this.lastMileService.update(id, dto);
+  async update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateLastMileDto) {
+    const record = await this.lastMileService.update(id, dto);
+    // Auto-generate invoice if distance or payment was updated
+    if (dto.exactKm !== undefined || dto.remainingPayment !== undefined) {
+      await this.lastMileInvoiceService.ensureInvoiceFor(record);
+    }
+    return record;
   }
 
   @Delete(':id')
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
index e6ed6634d..32b688069 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.module.ts
@@ -1,6 +1,7 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { BillingModule } from '../billing/billing.module';
 import { BookingsModule } from '../bookings/bookings.module';
 import { DriversModule } from '../drivers/drivers.module';
 import { NotificationsModule } from '../notifications/notifications.module';
@@ -8,19 +9,21 @@ import { VehiclesModule } from '../vehicles/vehicles.module';
 import { LastMile } from './entities/last-mile.entity';
 import { LastMileContainerAllocation } from './entities/last-mile-container-allocation.entity';
 import { LastMileController } from './last-mile.controller';
+import { LastMileInvoiceService } from './last-mile-invoice.service';
 import { LastMileRepository } from './last-mile.repository';
 import { LastMileService } from './last-mile.service';
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([LastMile, LastMileContainerAllocation]),
+    BillingModule,
     forwardRef(() => BookingsModule),
     VehiclesModule,
     DriversModule,
     NotificationsModule,
   ],
   controllers: [LastMileController],
-  providers: [LastMileRepository, LastMileService],
-  exports: [LastMileRepository, LastMileService],
+  providers: [LastMileRepository, LastMileService, LastMileInvoiceService],
+  exports: [LastMileRepository, LastMileService, LastMileInvoiceService],
 })
 export class LastMileModule {}

From 1193e2bfa957debc38c6f409c445d7c026b0d3e8 Mon Sep 17 00:00:00 2001
From: yaschalew <yaschalew10@gmail.com>
Date: Mon, 29 Jun 2026 18:35:51 +0300
Subject: [PATCH 28/63] fix commit

---
 apps/edr-freight-web/backoffice/src/constants/apiConfig.ts | 4 ++--
 apps/edr-freight-web/portal/src/constants/apiConfig.ts     | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index 7a7604cc7..1217b8762 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,6 +1,6 @@
-// export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
 
-export const API_BASE_URL = 'http://localhost:3001';
+// export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index a24cb4a6d..1b070d87d 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,5 @@
-// export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+// export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the

From ce3584cd4a59f411803032f990fa037d9179d73f Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 29 Jun 2026 15:41:00 +0000
Subject: [PATCH 29/63] cfix payment

---
 .../src/modules/payment/payment.service.ts          | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 71371989b..347fedc1e 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -462,16 +462,29 @@ export class PaymentService {
         failureCode?: string;
         failureMessage?: string;
     }): Promise<{ processed: boolean; alreadyFinalized?: boolean; reason?: string }> {
+        console.log(`Received payment event: ${JSON.stringify(event)}`);
         if (event.eventType === "payment.succeeded") {
             const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId });
             if (!intent) {
                 return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
             }
+            console.log(`Processing payment succeeded event for intent: }`,intent);
             const { alreadyFinalized } = await this.markIntentSucceeded(intent.id, {
                 providerTxnId: event.providerTxnId,
                 paidAt: event.paidAt ? new Date(event.paidAt) : undefined,
                 notify: true,
             });
+            console.log(`Payment finalized for intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
+
+            // When the intent references a booking, flip the booking itself paid.
+            // refId holds the booking id (the domain reference the intent opened with).
+            if (intent.referenceType === PaymentReferenceType.BOOKING) {
+                await this.datasource.manager.update(
+                    Booking,
+                    { id: intent.refId },
+                    { status: "PAID", paymentStatus: "PAID" },
+                );
+            }
             // console.log(`Payment finalized for booking ${event.referenceId}, intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
             return { processed: true, alreadyFinalized };
         }

From d91389daac5b9232cce0f01decc9bca60dac1d11 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 29 Jun 2026 15:46:17 +0000
Subject: [PATCH 30/63] cfix payment

---
 ...lumn.ts => 1810000000004-AddPostPaymentCompletedColumn.ts} | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 rename apps/edr-freight-api/src/migrations/{1719667261000-AddPostPaymentCompletedColumn.ts => 1810000000004-AddPostPaymentCompletedColumn.ts} (93%)

diff --git a/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts b/apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts
similarity index 93%
rename from apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts
rename to apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts
index c755d6356..aeedae2b1 100644
--- a/apps/edr-freight-api/src/migrations/1719667261000-AddPostPaymentCompletedColumn.ts
+++ b/apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts
@@ -1,7 +1,7 @@
 import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
 
-export class AddPostPaymentCompletedColumn1719667261000 implements MigrationInterface {
-  name = 'AddPostPaymentCompletedColumn1719667261000';
+export class AddPostPaymentCompletedColumn1810000000004 implements MigrationInterface {
+  name = 'AddPostPaymentCompletedColumn1810000000004';
 
   public async up(queryRunner: QueryRunner): Promise<void> {
     const firstMileTable = await queryRunner.hasTable('freight.first_mile_deliveries');

From 10cde2b2e3445d7ea6f497e574102f183f05addb Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 29 Jun 2026 19:44:40 +0000
Subject: [PATCH 31/63] fix

---
 apps/edr-freight-api/Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/Dockerfile b/apps/edr-freight-api/Dockerfile
index a9965c74a..b0850737b 100644
--- a/apps/edr-freight-api/Dockerfile
+++ b/apps/edr-freight-api/Dockerfile
@@ -34,4 +34,4 @@ RUN addgroup --system --gid 1001 nodejs \
 COPY --from=deployer --chown=nestjs:nodejs /deploy .
 USER nestjs
 EXPOSE 3001
-CMD ["sh", "-c", "pnpm run migrate && node dist/main.js"]
+CMD ["node", "dist/main.js"]

From 9bd7edbd03e547d9d301885a510eba68502a9a9f Mon Sep 17 00:00:00 2001
From: "Stephanos A." <steph.et@outlook.com>
Date: Tue, 30 Jun 2026 00:42:39 +0300
Subject: [PATCH 32/63] Update Dockerfile

---
 apps/edr-passenger-api/Dockerfile | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/edr-passenger-api/Dockerfile b/apps/edr-passenger-api/Dockerfile
index 1b5c8e9d3..4941ceb46 100644
--- a/apps/edr-passenger-api/Dockerfile
+++ b/apps/edr-passenger-api/Dockerfile
@@ -23,10 +23,10 @@ RUN pnpm turbo build --filter="@edr/passenger-api..."
 FROM base AS deployer
 COPY --from=builder /app/ .
 RUN pnpm deploy --filter="@edr/passenger-api" --legacy /deploy
-# Copy Prisma schema and generated client to deployment directory
-RUN mkdir -p /deploy/node_modules/.prisma /deploy/node_modules/@prisma && \
-    cp -r node_modules/.prisma/client /deploy/node_modules/.prisma/ 2>/dev/null || true && \
-    cp -r node_modules/@prisma/client /deploy/node_modules/@prisma/ 2>/dev/null || true
+# Copy prisma directory and generate client in deploy location
+RUN cp -r apps/edr-passenger-api/prisma /deploy/ && \
+    cd /deploy && \
+    npx prisma generate --schema=prisma/schema.prisma
 
 # --- Migration image: built in CI, run as a one-shot `docker run --rm --env-file ...`
 # against the real DB, as its own gated step *before* the app image is built/deployed.

From 3ceacbe9a9087498cf007111b7b09ad3d35bce35 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 02:03:20 +0000
Subject: [PATCH 33/63] fix(migrations): use CREATE TYPE IF NOT EXISTS for
 invoices enum

Allows migration to run when enum already exists in prod DB. Prevents
'type already exists' error on redeployment.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../src/migrations/1821000000002-CreateInvoices.ts              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 5c42cad65..09cb68262 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -16,7 +16,7 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
 
   public async up(queryRunner: QueryRunner): Promise<void> {
     await queryRunner.query(`
-      CREATE TYPE freight.invoices_status_enum AS ENUM (
+      CREATE TYPE IF NOT EXISTS freight.invoices_status_enum AS ENUM (
         'DRAFT',
         'PENDING',
         'PAID',

From ec82f8eb9fcd8186222a1f1c0f8e0e6860ddb320 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 02:03:20 +0000
Subject: [PATCH 34/63] fix(migrations): use CREATE TYPE IF NOT EXISTS for
 invoices enum

Allows migration to run when enum already exists in prod DB. Prevents
'type already exists' error on redeployment.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../1821000000002-CreateInvoices.ts           | 26 ++++++++++++-------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 5c42cad65..610fe6b30 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -15,16 +15,22 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
   name = "CreateInvoices1821000000002";
 
   public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`
-      CREATE TYPE freight.invoices_status_enum AS ENUM (
-        'DRAFT',
-        'PENDING',
-        'PAID',
-        'OVERDUE',
-        'CANCELLED',
-        'REFUNDED'
-      );
-    `);
+    const typeExists = await queryRunner.query(
+      `SELECT 1 FROM pg_type WHERE typname = 'invoices_status_enum' AND typnamespace = 'freight'::regnamespace;`,
+    );
+
+    if (!typeExists.length) {
+      await queryRunner.query(`
+        CREATE TYPE freight.invoices_status_enum AS ENUM (
+          'DRAFT',
+          'PENDING',
+          'PAID',
+          'OVERDUE',
+          'CANCELLED',
+          'REFUNDED'
+        );
+      `);
+    }
 
     await queryRunner.query(`
       CREATE TABLE freight.invoices (

From 76b25bd2145dbb561caa2da1d4add7c1beeb8c4c Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 02:33:29 +0000
Subject: [PATCH 35/63] fix

---
 .../1821000000002-CreateInvoices.ts           | 19 -------------------
 .../first-mile/entities/first-mile.entity.ts  |  4 ++--
 .../last-mile/entities/last-mile.entity.ts    |  4 ++--
 3 files changed, 4 insertions(+), 23 deletions(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 449863750..09cb68262 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -15,24 +15,6 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
   name = "CreateInvoices1821000000002";
 
   public async up(queryRunner: QueryRunner): Promise<void> {
-<<<<<<< HEAD
-    const typeExists = await queryRunner.query(
-      `SELECT 1 FROM pg_type WHERE typname = 'invoices_status_enum' AND typnamespace = 'freight'::regnamespace;`,
-    );
-
-    if (!typeExists.length) {
-      await queryRunner.query(`
-        CREATE TYPE freight.invoices_status_enum AS ENUM (
-          'DRAFT',
-          'PENDING',
-          'PAID',
-          'OVERDUE',
-          'CANCELLED',
-          'REFUNDED'
-        );
-      `);
-    }
-=======
     await queryRunner.query(`
       CREATE TYPE IF NOT EXISTS freight.invoices_status_enum AS ENUM (
         'DRAFT',
@@ -43,7 +25,6 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
         'REFUNDED'
       );
     `);
->>>>>>> 3ceacbe9a9087498cf007111b7b09ad3d35bce35
 
     await queryRunner.query(`
       CREATE TABLE freight.invoices (
diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
index b2eb3801f..319350b43 100644
--- a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
@@ -35,8 +35,8 @@ export class FirstMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  // @Column({ type: 'boolean', default: false })
-  // isPostPaymentCompleted!: boolean;
+  @Column({ type: 'boolean', default: false })
+  isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;
diff --git a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
index 61aad0d72..c1787cda8 100644
--- a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
@@ -35,8 +35,8 @@ export class LastMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  // @Column({ type: 'boolean', default: false })
-  // isPostPaymentCompleted!: boolean;
+  @Column({ type: 'boolean', default: false })
+  isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;

From f9ef473cffe9b23d19b15a5ad115433ba12f8d06 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 02:45:37 +0000
Subject: [PATCH 36/63] fix(migrations): check pg_type before CREATE TYPE enum

PostgreSQL doesn't support IF NOT EXISTS on CREATE TYPE AS ENUM.
Query pg_type table to check if enum exists before creating.
Compatible with all PostgreSQL versions.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../1821000000002-CreateInvoices.ts           | 26 ++++++++++++-------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 09cb68262..93196578d 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -15,16 +15,22 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
   name = "CreateInvoices1821000000002";
 
   public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`
-      CREATE TYPE IF NOT EXISTS freight.invoices_status_enum AS ENUM (
-        'DRAFT',
-        'PENDING',
-        'PAID',
-        'OVERDUE',
-        'CANCELLED',
-        'REFUNDED'
-      );
-    `);
+    const typeExists = await queryRunner.query(
+      `SELECT 1 FROM pg_type WHERE typname = 'invoices_status_enum' AND typnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'freight');`,
+    );
+
+    if (!typeExists.length) {
+      await queryRunner.query(`
+        CREATE TYPE freight.invoices_status_enum AS ENUM (
+          'DRAFT',
+          'PENDING',
+          'PAID',
+          'OVERDUE',
+          'CANCELLED',
+          'REFUNDED'
+        );
+      `);
+    }
 
     await queryRunner.query(`
       CREATE TABLE freight.invoices (

From b1d9045d0b790c93e9b9a2a520241afd6ac58212 Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 03:15:58 +0000
Subject: [PATCH 37/63] fix: remove isPostPaymentCompleted filter check

Property removed from entities until migration creates column.
Temporarily skip this filter until feature is fully implemented.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../backoffice/src/pages/operations/FirstMilePage.tsx            | 1 -
 .../backoffice/src/pages/operations/LastMilePage.tsx             | 1 -
 2 files changed, 2 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
index e17ea46c7..2b2f00904 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
@@ -530,7 +530,6 @@ const FirstMilePage = () => {
   };
 
   const matchesFilter = (r: FirstMileRecord) => {
-    if (filterPostPaymentPending && r.isPostPaymentCompleted) return false;
     switch (statusFilter) {
       case "ALL": return true;
       case "ASSIGNED": return isAssigned(r);
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
index 9798a90bf..e81f516e2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
@@ -509,7 +509,6 @@ const LastMilePage = () => {
   );
 
   const matchesFilter = (r: LastMileRecord) => {
-    if (filterPostPaymentPending && r.isPostPaymentCompleted) return false;
     switch (statusFilter) {
       case "ALL": return true;
       case "ASSIGNED": return isAssigned(r);

From 25e91c6d933cd7656904e960b69f40787a94576e Mon Sep 17 00:00:00 2001
From: natib21 <yaschalew10@gmail.com>
Date: Tue, 30 Jun 2026 03:33:54 +0000
Subject: [PATCH 38/63] fix: comment out isPostPaymentCompleted column
 decorator

Column doesn't exist in DB yet. Commenting out @Column decorator
prevents TypeORM from trying to select non-existent column.
Fixes 500 QueryFailedError on first-mile/last-mile list endpoints.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../src/modules/first-mile/entities/first-mile.entity.ts     | 5 +++--
 .../src/modules/last-mile/entities/last-mile.entity.ts       | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
index 513aaf98e..ef2ffb845 100644
--- a/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts
@@ -34,8 +34,9 @@ export class FirstMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  @Column({ type: 'boolean', default: false })
-  isPostPaymentCompleted!: boolean;
+  // TODO: uncomment after migration creates column
+  // @Column({ type: 'boolean', default: false })
+  // isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;
diff --git a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
index 6c8c9d1ca..0d342956f 100644
--- a/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/entities/last-mile.entity.ts
@@ -34,8 +34,9 @@ export class LastMile extends BaseEntity {
   @Column({ name: 'remaining_payment', type: 'numeric', precision: 14, scale: 2, default: 0 })
   remainingPayment!: number;
 
-  @Column({ type: 'boolean', default: false })
-  isPostPaymentCompleted!: boolean;
+  // TODO: uncomment after migration creates column
+  // @Column({ type: 'boolean', default: false })
+  // isPostPaymentCompleted!: boolean;
 
   @Column({ name: 'estimated_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   estimatedKm?: number | null;

From 9f5c22c1ee58f7eb915c3bc90bc3e067b82bccc1 Mon Sep 17 00:00:00 2001
From: hagiye <hageritina27@gmail.com>
Date: Tue, 30 Jun 2026 07:19:12 +0300
Subject: [PATCH 39/63] Goods recieved notes and Booking delivery

---
 apps/edr-freight-api/package.json             |   1 +
 ...000000-AddGrnNumberToWarehouseInventory.ts |  34 ++
 .../entities/warehouse-inventory.entity.ts    |   3 +
 .../warehouse-inventory.controller.ts         |  10 +
 .../warehouses/warehouse-inventory.service.ts | 439 ++++++++++++++++--
 .../seed-warehouse-export-receive-ready.ts    | 142 ++++++
 .../warehouses/InventoryDetailModal.tsx       |  12 +
 .../warehouses/ReceiveInventoryModal.tsx      | 174 +++++--
 .../warehouses/ReleaseOrderModal.tsx          | 201 ++++++--
 .../warehouses/WarehouseInventoryTable.tsx    |  68 ++-
 .../backoffice/src/constants/URLS.ts          |   1 +
 .../backoffice/src/constants/apiConfig.ts     |   4 +-
 .../warehouses/ExportWarehouseFlowPage.tsx    |  38 +-
 .../backoffice/src/services/api.ts            |   6 +-
 .../src/services/warehouse.service.ts         |   4 +
 .../backoffice/src/types/warehouse.ts         |   7 +
 .../portal/src/constants/apiConfig.ts         |   4 +-
 .../MyPortalPage/components/BookingRow.tsx    |   8 +
 .../BookingDetailPage/ReadonlyBookingView.tsx |  26 +-
 .../delivery/ApproveDeliveryButton.tsx        |  73 +++
 .../portal/src/services/api.ts                |   7 +
 21 files changed, 1126 insertions(+), 136 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts
 create mode 100644 apps/edr-freight-api/src/scripts/seed-warehouse-export-receive-ready.ts
 create mode 100644 apps/edr-freight-web/portal/src/pages/bookings/delivery/ApproveDeliveryButton.tsx

diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index 27737c84c..134bfd885 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -18,6 +18,7 @@
     "seed:demo-scheduling": "ts-node -r tsconfig-paths/register src/scripts/seed-demo-scheduling.ts",
     "seed:freight-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-freight-demo.ts",
     "seed:warehouse-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-warehouse-demo.ts",
+    "seed:warehouse-export-receive-ready": "ts-node -r tsconfig-paths/register src/scripts/seed-warehouse-export-receive-ready.ts",
     "seed:export-djibouti-interchange-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-export-djibouti-interchange-demo.ts",
     "seed:import-djibouti-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-import-djibouti-demo.ts",
     "seed:approved-first-lastmile-demo-bookings": "ts-node -r tsconfig-paths/register src/scripts/seed-approved-first-lastmile-demo-bookings.ts",
diff --git a/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts b/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts
new file mode 100644
index 000000000..c57a43aaa
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts
@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddGrnNumberToWarehouseInventory1828000000000 implements MigrationInterface {
+  name = 'AddGrnNumberToWarehouseInventory1828000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.warehouse_inventory
+      ADD COLUMN IF NOT EXISTS grn_number VARCHAR(100) NULL
+    `);
+
+    await queryRunner.query(`
+      UPDATE freight.warehouse_inventory
+         SET grn_number = substring(notes FROM 'GRN Number: ([^\\n\\r]+)')
+       WHERE grn_number IS NULL
+         AND notes IS NOT NULL
+         AND notes ~ 'GRN Number: '
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_warehouse_inventory_grn_number
+      ON freight.warehouse_inventory(grn_number)
+      WHERE grn_number IS NOT NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_warehouse_inventory_grn_number`);
+    await queryRunner.query(`
+      ALTER TABLE freight.warehouse_inventory
+      DROP COLUMN IF EXISTS grn_number
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-inventory.entity.ts b/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-inventory.entity.ts
index 815841e54..290b6f0c2 100644
--- a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-inventory.entity.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-inventory.entity.ts
@@ -110,6 +110,9 @@ export class WarehouseInventory extends BaseEntity {
   @Column({ name: 'volume', type: 'numeric', precision: 12, scale: 3, nullable: true })
   volume?: number | null;
 
+  @Column({ name: 'grn_number', type: 'varchar', length: 100, nullable: true })
+  grnNumber?: string | null;
+
   @Column({ name: 'status', type: 'varchar', length: 32, default: 'RECEIVED' })
   status!: WarehouseInventoryStatus;
 
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
index 68f536b33..6b2bd8c28 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
@@ -273,6 +273,16 @@ export class WarehouseInventoryController {
     return res.send(buffer);
   }
 
+  @Get(':id/grn-document')
+  @ApiOperation({ summary: 'View goods received note PDF' })
+  async grnDocument(@Param('id', ParseUUIDPipe) id: string, @Res() res: Response) {
+    const { filename, buffer } = await this.inventoryService.grnDocument(id);
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader('Content-Disposition', `inline; filename="${filename}"`);
+    res.setHeader('Content-Length', buffer.length);
+    return res.send(buffer);
+  }
+
   @Get(':id/handover-document')
   @ApiOperation({ summary: 'View import goods handover document PDF' })
   async handoverDocument(@Param('id', ParseUUIDPipe) id: string, @Res() res: Response) {
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
index 618553df3..001897b3f 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
@@ -52,6 +52,7 @@ const isLoadableWagonStatus = (status: string | null | undefined) =>
   LOADABLE_WAGON_STATUSES.includes(normalizeWagonStatus(status));
 
 const CUSTOMER_DELIVERY_APPROVAL_PREFIX = 'CUSTOMER_DELIVERY_APPROVAL:';
+const HANDOVER_DOCUMENT_MARKER = '[Handover Document]';
 
 export interface InventoryInquiryResult {
   id: string;
@@ -249,6 +250,7 @@ export interface ReadyToLoadRow {
   containerNumber: string | null;
   cargoType: string | null;
   weight: number | null;
+  grnNumber: string | null;
   origin: string | null;
   destination: string | null;
   inspectionStatus: string | null;
@@ -295,6 +297,7 @@ export interface ImportUnloadedRow {
   containerNumber: string | null;
   cargoType: string | null;
   weight: number | null;
+  grnNumber: string | null;
   trainSchedule: string | null;
   inspectionStatus: string | null;
   pickupOption: string;
@@ -302,6 +305,8 @@ export interface ImportUnloadedRow {
   currentStatus: string;
   releaseDate: string | null;
   releaseOrderReference: string | null;
+  handoverDocumentReference: string | null;
+  handoverDocumentDate: string | null;
   deliveredAt: string | null;
 }
 
@@ -415,7 +420,10 @@ export class WarehouseInventoryService {
 
     const search = filter.search?.trim();
     const where: FindManyOptions<WarehouseInventory>['where'] = search
-      ? { ...base, notes: ILike(`%${search}%`) }
+      ? [
+          { ...base, notes: ILike(`%${search}%`) },
+          { ...base, grnNumber: ILike(`%${search}%`) },
+        ]
       : base;
 
     const items = await this.inventoryRepository.findAll({
@@ -766,6 +774,7 @@ export class WarehouseInventoryService {
         const [booking] = await manager.query(
           `SELECT b.reference AS "reference",
                   b.payment_status AS "paymentStatus",
+                  b.freight_type AS "freightType",
                   b.cargo_total_weight_vgm AS "weight",
                   company.name AS "customer",
                   company.tin AS "customerTin",
@@ -847,6 +856,12 @@ export class WarehouseInventoryService {
         const existing = await manager.getRepository(WarehouseInventory).findOne({ where: { bookingId } });
         if (existing) { skip('Already received'); continue; }
 
+        const containerQuantity = Number(booking.containerQuantity ?? 0);
+        if (booking.freightType === 'CONTAINER' && containerQuantity <= 0) {
+          skip('Container booking has no container quantity');
+          continue;
+        }
+
         const now = new Date();
         const grnNumber = this.generateGrnNumber(dto.direction, bookingId, now);
         const truckEntrance = dto.truckEntrance
@@ -867,8 +882,9 @@ export class WarehouseInventoryService {
             yardId: dto.yardId,
             zoneId: dto.zoneId,
             bookingId,
-            quantity: Number(booking.containerQuantity) || 1,
+            quantity: booking.freightType === 'CONTAINER' ? containerQuantity : 1,
             weight: Number(booking.weight) || 0,
+            grnNumber,
             status: 'RECEIVED',
             arrivedAt: now,
             notes: receiveNote,
@@ -962,6 +978,7 @@ export class WarehouseInventoryService {
               ct.container_number      AS "containerNumber",
               COALESCE(cgt.cargo_type_name, b.cargo_free_text) AS "cargoType",
               inv.weight               AS "weight",
+              COALESCE(inv.grn_number, substring(inv.notes FROM 'GRN Number: ([^\\n\\r]+)')) AS "grnNumber",
               oy.code                  AS "origin",
               dy.code                  AS "destination",
               oy.country               AS "originCountry",
@@ -1021,6 +1038,7 @@ export class WarehouseInventoryService {
                 ORDER BY c.container_number LIMIT 1) AS "containerNumber",
               COALESCE(cgt.cargo_type_name, b.cargo_free_text) AS "cargoType",
               inv.weight               AS "weight",
+              COALESCE(inv.grn_number, substring(inv.notes FROM 'GRN Number: ([^\\n\\r]+)')) AS "grnNumber",
               ts.train_number          AS "trainSchedule",
               inv.inspection_status    AS "inspectionStatus",
               CASE WHEN b.last_mile_delivery_address IS NOT NULL
@@ -1029,6 +1047,8 @@ export class WarehouseInventoryService {
               inv.status               AS "currentStatus",
               inv.release_date         AS "releaseDate",
               inv.release_order_reference AS "releaseOrderReference",
+              substring(inv.notes FROM 'Handover Reference: ([^\\n\\r]+)') AS "handoverDocumentReference",
+              substring(inv.notes FROM 'Generated At: ([^\\n\\r]+)') AS "handoverDocumentDate",
               inv.delivered_at         AS "deliveredAt",
               oy.country               AS "originCountry",
               dy.country               AS "destinationCountry"
@@ -1669,6 +1689,7 @@ export class WarehouseInventoryService {
           quantity,
           weight,
           volume: dto.volume ?? null,
+          grnNumber,
           status: 'RECEIVED',
           arrivedAt: now,
           notes: receiveNote,
@@ -1933,24 +1954,31 @@ export class WarehouseInventoryService {
       );
     }
 
-    const releaseDate = dto.releaseDate ? new Date(dto.releaseDate) : new Date();
-    const reference = dto.reference?.trim() || null;
+    const isTruckLeaving = dto.grossWeight !== undefined && Boolean(dto.gateOutTime);
+    const releaseDate = isTruckLeaving
+      ? dto.releaseDate ? new Date(dto.releaseDate) : new Date()
+      : item.releaseDate ?? null;
+    const reference = dto.reference?.trim() || (await this.generateReleaseReference(item));
     const exitInspectionNote = this.buildExitInspectionNote(dto);
 
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(WarehouseInventory).update(id, {
         releaseDate,
         releaseOrderReference: reference,
-        notes: [item.notes?.trim(), exitInspectionNote].filter(Boolean).join('\n\n'),
+        notes: this.replaceExitInspectionNote(item.notes, exitInspectionNote),
       });
       await this.activityLog.record(
         {
           activityType: 'INVENTORY_RELEASED',
           inventoryId: id,
           warehouseId: item.warehouseId,
-          description: reference
-            ? `Release order ${reference} sent to customer`
-            : 'Release order sent to customer',
+          description: isTruckLeaving
+            ? reference
+              ? `Exit paper ${reference} generated`
+              : 'Exit paper generated'
+            : reference
+              ? `Truck arrival ${reference} registered`
+              : 'Truck arrival registered',
           performedBy: dto.performedBy,
         },
         manager,
@@ -2039,6 +2067,106 @@ export class WarehouseInventoryService {
   }
 
   /** Hand import goods to the customer + capture proof of delivery (READY_FOR_PICKUP → DELIVERED). */
+  async grnDocument(id: string): Promise<{ filename: string; buffer: Buffer }> {
+    const [row] = await this.dataSource.query(
+      `SELECT inv.id,
+              COALESCE(inv.grn_number, substring(inv.notes FROM 'GRN Number: ([^\\n\\r]+)')) AS "grnNumber",
+              COALESCE(inv.arrived_at, inv.created_at) AS "receivedAt",
+              inv.quantity,
+              inv.weight,
+              inv.volume,
+              inv.status,
+              inv.notes,
+              b.id AS "bookingId",
+              b.reference AS "bookingReference",
+              b.status AS "bookingStatus",
+              b.freight_type AS "freightType",
+              b.trade_direction AS "tradeDirection",
+              b.cargo_total_weight_vgm AS "bookingDeclaredWeight",
+              company.name AS "customerName",
+              company.tin AS "customerTin",
+              service_type.service_name AS "serviceType",
+              origin_yard.label AS "originYardLabel",
+              origin_yard.code AS "originYardCode",
+              destination_yard.label AS "destinationYardLabel",
+              destination_yard.code AS "destinationYardCode",
+              COALESCE(container.container_number, booking_container.container_number) AS "containerNumber",
+              booking_container."containerSummary" AS "bookingContainerSummary",
+              COALESCE(cargo_type.cargo_type_name, b.cargo_free_text, cargo.description) AS "cargoDescription",
+              wh.name AS "warehouseName",
+              wh.code AS "warehouseCode",
+              yard.name AS "yardName",
+              yard.code AS "yardCode",
+              zone.name AS "zoneName",
+              zone.code AS "zoneCode"
+         FROM freight.warehouse_inventory inv
+         LEFT JOIN freight.bookings b ON b.id = inv.booking_id
+         LEFT JOIN freight.companies company ON company.id = b.company_id
+         LEFT JOIN freight.service_types service_type ON service_type.id = b.service_type_id
+         LEFT JOIN freight.yards origin_yard ON origin_yard.id = b.origin_yard_id
+         LEFT JOIN freight.yards destination_yard ON destination_yard.id = b.destination_yard_id
+         LEFT JOIN freight.warehouses wh ON wh.id = inv.warehouse_id
+         LEFT JOIN freight.warehouse_yards yard ON yard.id = inv.yard_id
+         LEFT JOIN freight.warehouse_zones zone ON zone.id = inv.zone_id
+         LEFT JOIN freight.containers container ON container.id = inv.container_id AND container.deleted_at IS NULL
+         LEFT JOIN LATERAL (
+           SELECT MIN(bc.container_number) AS container_number,
+                  STRING_AGG(
+                    CONCAT_WS(' ', bc.quantity::text, COALESCE(ct.label, ct.code, 'container')),
+                    ', '
+                    ORDER BY COALESCE(ct.label, ct.code, bc.container_type_id::text)
+                  ) AS "containerSummary"
+             FROM freight.booking_container bc
+             LEFT JOIN freight.container_types ct ON ct.id = bc.container_type_id
+            WHERE bc.booking_id = b.id
+              AND bc.deleted_at IS NULL
+         ) booking_container ON true
+         LEFT JOIN freight.cargoes cargo ON cargo.id = inv.cargo_id AND cargo.deleted_at IS NULL
+         LEFT JOIN freight.cargo_types cargo_type ON cargo_type.id = COALESCE(cargo.cargo_type_id, b.cargo_type_id)
+        WHERE inv.id = $1 AND inv.deleted_at IS NULL
+        LIMIT 1`,
+      [id],
+    );
+    if (!row) {
+      throw new NotFoundException(`Inventory item ${id} not found`);
+    }
+    if (!row.grnNumber) {
+      throw new BadRequestException('GRN number is missing for this inventory item');
+    }
+
+    const html = this.buildGrnDocumentHtml({
+      grnNumber: row.grnNumber,
+      receivedAt: row.receivedAt ? new Date(row.receivedAt) : new Date(),
+      bookingReference: row.bookingReference ?? row.bookingId ?? 'N/A',
+      bookingStatus: row.bookingStatus ?? null,
+      customerName: row.customerName ?? null,
+      customerTin: row.customerTin ?? null,
+      serviceType: row.serviceType ?? null,
+      freightType: row.freightType ?? null,
+      tradeDirection: row.tradeDirection ?? null,
+      route: [row.originYardLabel ?? row.originYardCode, row.destinationYardLabel ?? row.destinationYardCode]
+        .filter(Boolean)
+        .join(' to ') || null,
+      containerNumber: row.containerNumber ?? null,
+      bookingContainerSummary: row.bookingContainerSummary ?? null,
+      cargoDescription: row.cargoDescription ?? null,
+      quantity: Number(row.quantity ?? 0),
+      weight: Number(row.weight ?? 0),
+      volume: row.volume == null ? null : Number(row.volume),
+      bookingDeclaredWeight: Number(row.bookingDeclaredWeight ?? 0),
+      warehouse: [row.warehouseName, row.warehouseCode].filter(Boolean).join(' / ') || null,
+      yard: [row.yardName, row.yardCode].filter(Boolean).join(' / ') || null,
+      zone: [row.zoneName, row.zoneCode].filter(Boolean).join(' / ') || null,
+      inventoryStatus: row.status ?? null,
+      receiveSummary: this.extractReceiveSummary(row.notes),
+    });
+
+    return {
+      filename: `grn-${String(row.grnNumber).replace(/[^a-zA-Z0-9_-]+/g, '-')}.pdf`,
+      buffer: await this.releaseDocuments.htmlToPdfBuffer(html),
+    };
+  }
+
   async approveDeliveryForBooking(
     bookingId: string,
     userId?: string,
@@ -2121,8 +2249,17 @@ export class WarehouseInventoryService {
               b.status AS "bookingStatus",
               b.freight_type AS "freightType",
               b.trade_direction AS "tradeDirection",
+              b.scheduled_date AS "scheduledDate",
+              b.cargo_total_weight_vgm AS "bookingDeclaredWeight",
+              b.last_mile_delivery_address AS "lastMileDeliveryAddress",
               company.name AS "customerName",
+              service_type.service_name AS "serviceType",
+              origin_yard.label AS "originYardLabel",
+              origin_yard.code AS "originYardCode",
+              destination_yard.label AS "destinationYardLabel",
+              destination_yard.code AS "destinationYardCode",
               COALESCE(container.container_number, booking_container.container_number) AS "containerNumber",
+              booking_container."containerSummary" AS "bookingContainerSummary",
               COALESCE(cargo_type.cargo_type_name, b.cargo_free_text, cargo.description) AS "cargoDescription",
               wh.name AS "warehouseName",
               wh.code AS "warehouseCode",
@@ -2134,14 +2271,25 @@ export class WarehouseInventoryService {
          FROM freight.warehouse_inventory inv
          LEFT JOIN freight.bookings b ON b.id = inv.booking_id
          LEFT JOIN freight.companies company ON company.id = b.company_id
+         LEFT JOIN freight.service_types service_type ON service_type.id = b.service_type_id
+         LEFT JOIN freight.yards origin_yard ON origin_yard.id = b.origin_yard_id
+         LEFT JOIN freight.yards destination_yard ON destination_yard.id = b.destination_yard_id
          LEFT JOIN freight.warehouses wh ON wh.id = inv.warehouse_id
          LEFT JOIN freight.warehouse_yards yard ON yard.id = inv.yard_id
          LEFT JOIN freight.warehouse_zones zone ON zone.id = inv.zone_id
          LEFT JOIN freight.containers container ON container.id = inv.container_id AND container.deleted_at IS NULL
-         LEFT JOIN freight.booking_container booking_container ON (
-           booking_container.booking_id = b.id
-           AND booking_container.deleted_at IS NULL
-         )
+         LEFT JOIN LATERAL (
+           SELECT MIN(bc.container_number) AS container_number,
+                  STRING_AGG(
+                    CONCAT_WS(' ', bc.quantity::text, COALESCE(ct.label, ct.code, 'container')),
+                    ', '
+                    ORDER BY COALESCE(ct.label, ct.code, bc.container_type_id::text)
+                  ) AS "containerSummary"
+             FROM freight.booking_container bc
+             LEFT JOIN freight.container_types ct ON ct.id = bc.container_type_id
+            WHERE bc.booking_id = b.id
+              AND bc.deleted_at IS NULL
+         ) booking_container ON true
          LEFT JOIN freight.cargoes cargo ON cargo.id = inv.cargo_id AND cargo.deleted_at IS NULL
          LEFT JOIN freight.cargo_types cargo_type ON cargo_type.id = COALESCE(cargo.cargo_type_id, b.cargo_type_id)
          LEFT JOIN freight.train_schedule_bookings tsb ON tsb.booking_id = b.id AND tsb.deleted_at IS NULL
@@ -2158,18 +2306,37 @@ export class WarehouseInventoryService {
     }
 
     const bookingReference = row.bookingReference || row.bookingId || 'N/A';
+    const reference =
+      this.extractHandoverDocumentLine(row.notes, 'Handover Reference') ||
+      `HND-${String(bookingReference).replace(/[^a-zA-Z0-9_-]+/g, '-')}`;
+    const generatedAtValue = this.extractHandoverDocumentLine(row.notes, 'Generated At');
+    const generatedAt = generatedAtValue ? new Date(generatedAtValue) : new Date();
+    const handedOverAt = Number.isNaN(generatedAt.getTime()) ? new Date() : generatedAt;
+    if (!generatedAtValue) {
+      await this.inventoryRepository.update(id, {
+        notes: this.replaceHandoverDocumentNote(row.notes, this.buildHandoverDocumentNote(reference, handedOverAt)),
+      });
+    }
+
     const html = this.buildHandoverDocumentHtml({
-      reference: `HND-${String(bookingReference).replace(/[^a-zA-Z0-9_-]+/g, '-')}`,
-      handedOverAt: new Date(row.handoverDate ?? Date.now()),
+      reference,
+      handedOverAt,
       bookingReference,
       bookingStatus: row.bookingStatus ?? null,
       customerName: row.customerName ?? null,
+      serviceType: row.serviceType ?? null,
       freightType: row.freightType ?? null,
       tradeDirection: row.tradeDirection ?? null,
+      route: [row.originYardLabel ?? row.originYardCode, row.destinationYardLabel ?? row.destinationYardCode]
+        .filter(Boolean)
+        .join(' to ') || null,
+      scheduledDate: row.scheduledDate ? new Date(row.scheduledDate) : null,
       containerNumber: row.containerNumber ?? null,
+      bookingContainerSummary: row.bookingContainerSummary ?? null,
       cargoDescription: row.cargoDescription ?? null,
       quantity: Number(row.quantity ?? 0),
       weight: Number(row.weight ?? 0),
+      bookingDeclaredWeight: Number(row.bookingDeclaredWeight ?? 0),
       warehouse: [row.warehouseName, row.warehouseCode].filter(Boolean).join(' / ') || null,
       yard: [row.yardName, row.yardCode].filter(Boolean).join(' / ') || null,
       zone: [row.zoneName, row.zoneCode].filter(Boolean).join(' / ') || null,
@@ -2178,11 +2345,12 @@ export class WarehouseInventoryService {
       releaseOrderReference: row.releaseOrderReference ?? null,
       releaseDate: row.releaseDate ? new Date(row.releaseDate) : null,
       trainSchedule: row.trainSchedule ?? null,
+      lastMileDeliveryAddress: row.lastMileDeliveryAddress ?? null,
       customerApproval: this.extractCustomerDeliveryApproval(row.notes),
     });
 
     return {
-      filename: `handover-${String(bookingReference).replace(/[^a-zA-Z0-9_-]+/g, '-')}.pdf`,
+      filename: `handover-${String(reference).replace(/[^a-zA-Z0-9_-]+/g, '-')}.pdf`,
       buffer: await this.releaseDocuments.htmlToPdfBuffer(html),
     };
   }
@@ -2666,6 +2834,128 @@ export class WarehouseInventoryService {
     return this.findById(id);
   }
 
+  private buildGrnDocumentHtml(data: {
+    grnNumber: string;
+    receivedAt: Date;
+    bookingReference: string;
+    bookingStatus: string | null;
+    customerName: string | null;
+    customerTin: string | null;
+    serviceType: string | null;
+    freightType: string | null;
+    tradeDirection: string | null;
+    route: string | null;
+    containerNumber: string | null;
+    bookingContainerSummary: string | null;
+    cargoDescription: string | null;
+    quantity: number;
+    weight: number;
+    volume: number | null;
+    bookingDeclaredWeight: number;
+    warehouse: string | null;
+    yard: string | null;
+    zone: string | null;
+    inventoryStatus: string | null;
+    receiveSummary: string | null;
+  }): string {
+    const esc = (value: unknown) =>
+      String(value ?? '-')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    const receivedAt = data.receivedAt.toLocaleString('en-GB', {
+      year: 'numeric',
+      month: 'short',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+    const rows: Array<[string, unknown]> = [
+      ['Booking Reference', data.bookingReference],
+      ['Customer / Consignee', data.customerName],
+      ['Customer TIN', data.customerTin],
+      ['Booking Status', data.bookingStatus],
+      ['Service Type', data.serviceType],
+      ['Freight Type', data.freightType],
+      ['Trade Direction', data.tradeDirection],
+      ['Route', data.route],
+      ['Container Number', data.containerNumber],
+      ['Booking Containers', data.bookingContainerSummary],
+      ['Cargo / Goods Description', data.cargoDescription],
+      ['Quantity', data.quantity],
+      ['Received Weight', `${data.weight.toLocaleString()} kg`],
+      ['Booking Declared Weight', data.bookingDeclaredWeight ? `${data.bookingDeclaredWeight.toLocaleString()} kg` : null],
+      ['Volume', data.volume == null ? null : data.volume.toLocaleString()],
+      ['Warehouse', data.warehouse],
+      ['Yard', data.yard],
+      ['Zone', data.zone],
+      ['Inventory Status', data.inventoryStatus],
+      ...(data.receiveSummary ? [['Receive Details', data.receiveSummary] as [string, string]] : []),
+    ];
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>Goods Received Note</title>
+  <style>
+    * { box-sizing: border-box; }
+    @page { size: A4; margin: 12mm 15mm 14mm; }
+    body { font-family: "Times New Roman", Georgia, serif; color: #061323; margin: 0; background: #fff; }
+    .top { display: grid; grid-template-columns: 1fr 210px; gap: 24px; border-top: 5px solid #0f766e; padding-top: 18px; }
+    .brand { font-size: 12px; color: #064c27; text-transform: uppercase; letter-spacing: .13em; font-weight: 800; }
+    h1 { margin: 8px 0 0; font-size: 31px; line-height: .98; text-transform: uppercase; letter-spacing: .02em; }
+    .subtitle { margin-top: 12px; font-size: 11px; color: #3d516a; text-transform: uppercase; letter-spacing: .14em; }
+    .ref { text-align: right; font-size: 11px; color: #334155; padding-top: 8px; }
+    .ref strong { display: block; color: #061323; font-size: 18px; margin: 5px 0 8px; letter-spacing: .02em; }
+    .rule { height: 3px; background: #0f766e; margin: 16px 0 22px; }
+    .notice { width: 76%; margin: 0 0 18px; padding: 13px 18px; background: #f0fdfa; border: 1px solid #5eead4; border-left: 5px solid #0f766e; font-size: 13px; line-height: 1.45; }
+    .section-title { margin: 18px 0 8px; font-size: 13px; font-weight: 800; color: #0f766e; text-transform: uppercase; letter-spacing: .12em; }
+    table { width: 100%; border-collapse: collapse; }
+    th { width: 31%; text-align: left; color: #0f2744; background: #f8fafc; font-weight: 800; }
+    th, td { border: 1px solid #b9c7d8; padding: 8px 10px; font-size: 12.2px; vertical-align: top; white-space: pre-line; }
+    .clause { margin-top: 14px; border: 1px solid #b9c7d8; padding: 12px 15px; font-size: 12.2px; line-height: 1.45; }
+    .signatures { display: grid; grid-template-columns: 1fr 1fr; gap: 34px; align-items: start; margin-top: 42px; }
+    .line { border-top: 1.4px solid #061323; padding-top: 7px; font-size: 10.8px; color: #24384f; min-height: 42px; }
+  </style>
+</head>
+<body>
+  <div class="top">
+    <div>
+      <div class="brand">Ethio-Djibouti Railway S.C.</div>
+      <h1>Goods Received Note</h1>
+      <div class="subtitle">Warehouse receiving confirmation</div>
+    </div>
+    <div class="ref">
+      GRN Number
+      <strong>${esc(data.grnNumber)}</strong>
+      Received: ${esc(receivedAt)}
+    </div>
+  </div>
+  <div class="rule"></div>
+  <div class="notice">
+    This Goods Received Note confirms that the listed goods were received into EDR warehouse custody at the stated location.
+  </div>
+  <div class="section-title">Receiving Particulars</div>
+  <table>
+    <tbody>
+      ${rows.map(([label, value]) => `<tr><th>${esc(label)}</th><td>${esc(value)}</td></tr>`).join('')}
+    </tbody>
+  </table>
+  <div class="section-title">Receipt Clause</div>
+  <div class="clause">
+    This document records warehouse receipt only. Loading, dispatch, release, delivery, customs, and fee clearance remain subject to their respective operational approvals.
+  </div>
+  <div class="signatures">
+    <div class="line">Warehouse receiver name / signature / date</div>
+    <div class="line">Driver or customer representative name / signature / date</div>
+  </div>
+</body>
+</html>`;
+  }
+
   private buildReleaseDocumentHtml(data: {
     reference: string;
     issuedAt: Date;
@@ -2721,7 +3011,7 @@ export class WarehouseInventoryService {
 <html>
 <head>
   <meta charset="utf-8" />
-  <title>Warehouse Gate Clearance / Release Order</title>
+  <title>Warehouse Release / Exit Paper</title>
   <style>
     * { box-sizing: border-box; }
     @page { size: A4; margin: 12mm 15mm 14mm; }
@@ -2752,8 +3042,8 @@ export class WarehouseInventoryService {
     <div class="top">
       <div>
         <div class="brand">Ethio-Djibouti Railway S.C.</div>
-        <h1>Warehouse Gate Clearance / Release Order</h1>
-        <div class="subtitle">Official warehouse release and exit authorization</div>
+        <h1>Warehouse Release / Exit Paper</h1>
+        <div class="subtitle">Official gate clearance and warehouse exit authorization</div>
       </div>
       <div class="ref">
         Document / Release No.
@@ -2763,7 +3053,7 @@ export class WarehouseInventoryService {
     </div>
     <div class="rule"></div>
     <div class="notice">
-      This clearance document confirms that the listed booking/goods are authorized for warehouse exit, subject to gate identity verification and confirmation that no blocking warehouse fees remain unpaid.
+      This Exit Paper confirms that the listed booking/goods are authorized for warehouse exit, subject to gate identity verification and confirmation that no blocking warehouse fees remain unpaid.
     </div>
     <div class="section-title">Release Particulars</div>
     <table>
@@ -2792,12 +3082,17 @@ export class WarehouseInventoryService {
     bookingReference: string;
     bookingStatus: string | null;
     customerName: string | null;
+    serviceType: string | null;
     freightType: string | null;
     tradeDirection: string | null;
+    route: string | null;
+    scheduledDate: Date | null;
     containerNumber: string | null;
+    bookingContainerSummary: string | null;
     cargoDescription: string | null;
     quantity: number;
     weight: number;
+    bookingDeclaredWeight: number;
     warehouse: string | null;
     yard: string | null;
     zone: string | null;
@@ -2806,6 +3101,7 @@ export class WarehouseInventoryService {
     releaseOrderReference: string | null;
     releaseDate: Date | null;
     trainSchedule: string | null;
+    lastMileDeliveryAddress: string | null;
     customerApproval: {
       approvedAt: string;
       signerDisplayName: string;
@@ -2835,13 +3131,18 @@ export class WarehouseInventoryService {
       ['Booking Reference', data.bookingReference],
       ['Customer / Consignee', data.customerName],
       ['Booking Status', data.bookingStatus],
+      ['Service Type', data.serviceType],
       ['Freight Type', data.freightType],
       ['Trade Direction', data.tradeDirection],
+      ['Route', data.route],
+      ['Scheduled Date', fmt(data.scheduledDate)],
       ['Train Schedule', data.trainSchedule],
       ['Container Number', data.containerNumber],
+      ['Booking Containers', data.bookingContainerSummary],
       ['Cargo / Goods Description', data.cargoDescription],
       ['Quantity', data.quantity],
-      ['Declared Weight', `${data.weight.toLocaleString()} kg`],
+      ['Inventory Weight', `${data.weight.toLocaleString()} kg`],
+      ['Booking Declared Weight', data.bookingDeclaredWeight ? `${data.bookingDeclaredWeight.toLocaleString()} kg` : null],
       ['Warehouse', data.warehouse],
       ['Yard', data.yard],
       ['Zone', data.zone],
@@ -2849,6 +3150,7 @@ export class WarehouseInventoryService {
       ['Inspection Status', data.inspectionStatus],
       ['Release Order', data.releaseOrderReference],
       ['Release Date', fmt(data.releaseDate)],
+      ['Last-mile Delivery Address', data.lastMileDeliveryAddress],
     ];
     const approval = data.customerApproval;
 
@@ -2898,7 +3200,8 @@ export class WarehouseInventoryService {
   </div>
   <div class="rule"></div>
   <div class="notice">
-    This document confirms EDR handed over the listed import goods to the customer after warehouse inspection passed.
+    This handover document is separate from the warehouse Exit Paper. It records the booking, route, cargo, container,
+    inspection, release, and customer approval details for the goods being handed to the customer.
   </div>
   <div class="section-title">Handover Particulars</div>
   <table>
@@ -2911,7 +3214,9 @@ export class WarehouseInventoryService {
     <tbody>
       <tr><th>1. Goods</th><td>${esc(data.cargoDescription || data.containerNumber || data.bookingReference)}</td></tr>
       <tr><th>Container</th><td>${esc(data.containerNumber)}</td></tr>
-      <tr><th>Weight</th><td>${esc(`${data.weight.toLocaleString()} kg`)}</td></tr>
+      <tr><th>Booking Containers</th><td>${esc(data.bookingContainerSummary)}</td></tr>
+      <tr><th>Inventory Weight</th><td>${esc(`${data.weight.toLocaleString()} kg`)}</td></tr>
+      <tr><th>Booking Declared Weight</th><td>${esc(data.bookingDeclaredWeight ? `${data.bookingDeclaredWeight.toLocaleString()} kg` : null)}</td></tr>
     </tbody>
   </table>
   <div class="section-title">Handover Clause</div>
@@ -3156,6 +3461,21 @@ export class WarehouseInventoryService {
     return `GRN-${direction.toUpperCase()}-${stamp}-${suffix}`;
   }
 
+  private async generateReleaseReference(item: WarehouseInventory): Promise<string> {
+    let bookingReference = item.booking?.reference;
+    if (!bookingReference && item.bookingId) {
+      const [booking]: Array<{ reference: string | null }> = await this.dataSource.query(
+        `SELECT reference FROM freight.bookings WHERE id = $1 AND deleted_at IS NULL LIMIT 1`,
+        [item.bookingId],
+      );
+      bookingReference = booking?.reference ?? undefined;
+    }
+    if (bookingReference) {
+      return `REL-${String(bookingReference).replace(/^BK-?/i, '')}`;
+    }
+    return `REL-${new Date().toISOString().slice(0, 10).replace(/-/g, '')}-${item.id.replace(/-/g, '').slice(0, 8).toUpperCase()}`;
+  }
+
   private buildExitInspectionNote(dto: ReleaseOrderDto): string | null {
     const hasExitInspection =
       Boolean(dto.truckPlateNumber?.trim()) ||
@@ -3179,17 +3499,27 @@ export class WarehouseInventoryService {
     if (!dto.driverName?.trim()) {
       throw new BadRequestException('Driver name is required for exit inspection');
     }
-    if (dto.tareWeight === undefined || dto.grossWeight === undefined) {
-      throw new BadRequestException('Tare weight and gross weight are required for exit inspection');
+    if (dto.tareWeight === undefined) {
+      throw new BadRequestException('Tare weight is required for truck arrival');
     }
 
     const tareWeight = Number(dto.tareWeight);
-    const grossWeight = Number(dto.grossWeight);
-    const computedNetWeight = Number((grossWeight - tareWeight).toFixed(3));
-    const submittedNetWeight = dto.netWeight === undefined ? computedNetWeight : Number(dto.netWeight);
+    const grossWeight = dto.grossWeight === undefined ? null : Number(dto.grossWeight);
+    const computedNetWeight =
+      grossWeight == null ? null : Number((grossWeight - tareWeight).toFixed(3));
+    const submittedNetWeight =
+      dto.netWeight === undefined || computedNetWeight == null ? computedNetWeight : Number(dto.netWeight);
 
-    if (Math.abs(submittedNetWeight - computedNetWeight) > 0.001) {
-      throw new BadRequestException('Weight mismatch: net weight must equal gross weight minus tare weight.');
+    if (grossWeight != null && !dto.gateOutTime) {
+      throw new BadRequestException('Gate out time is required for truck exit');
+    }
+    if (grossWeight != null && computedNetWeight != null && submittedNetWeight != null) {
+      if (Math.abs(submittedNetWeight - computedNetWeight) > 0.001) {
+        throw new BadRequestException('Weight mismatch: net weight must equal gross weight minus tare weight.');
+      }
+    }
+    if ((dto.grossWeight !== undefined || dto.gateOutTime || dto.netWeight !== undefined) && grossWeight == null) {
+      throw new BadRequestException('Gross weight is required for truck exit');
     }
 
     const rows = [
@@ -3205,14 +3535,27 @@ export class WarehouseInventoryService {
       dto.containerNumber?.trim() ? `Container Number: ${dto.containerNumber.trim()}` : null,
       dto.gateInTime ? `Gate In Time: ${dto.gateInTime}` : null,
       `Tare Weight: ${tareWeight} kg`,
-      `Gross Weight: ${grossWeight} kg`,
-      `Net Weight: ${computedNetWeight} kg`,
+      grossWeight == null ? null : `Gross Weight: ${grossWeight} kg`,
+      computedNetWeight == null ? null : `Net Weight: ${computedNetWeight} kg`,
       dto.gateOutTime ? `Gate Out Time: ${dto.gateOutTime}` : null,
     ];
 
     return rows.filter(Boolean).join('\n');
   }
 
+  private replaceExitInspectionNote(notes: string | null | undefined, exitInspectionNote: string | null): string | null {
+    const trimmed = notes?.trim();
+    if (!exitInspectionNote) return trimmed || null;
+    if (!trimmed) return exitInspectionNote;
+
+    const marker = '[Exit Inspection]';
+    const index = trimmed.lastIndexOf(marker);
+    if (index < 0) {
+      return `${trimmed}\n\n${exitInspectionNote}`;
+    }
+    return [trimmed.slice(0, index).trim(), exitInspectionNote].filter(Boolean).join('\n\n');
+  }
+
   private extractExitInspectionNote(notes?: string | null): string | null {
     if (!notes) return null;
     const marker = '[Exit Inspection]';
@@ -3221,6 +3564,40 @@ export class WarehouseInventoryService {
     return notes.slice(index + marker.length).trim() || null;
   }
 
+  private extractReceiveSummary(notes?: string | null): string | null {
+    if (!notes?.trim()) return null;
+    const withoutExit = notes.split('\n\n[Exit Inspection]')[0] ?? notes;
+    const withoutHandover = withoutExit.split(`\n\n${HANDOVER_DOCUMENT_MARKER}`)[0] ?? withoutExit;
+    return this.stripCustomerDeliveryApproval(withoutHandover)?.trim() || withoutHandover.trim() || null;
+  }
+
+  private buildHandoverDocumentNote(reference: string, generatedAt: Date): string {
+    return [
+      HANDOVER_DOCUMENT_MARKER,
+      `Handover Reference: ${reference}`,
+      `Generated At: ${generatedAt.toISOString()}`,
+    ].join('\n');
+  }
+
+  private replaceHandoverDocumentNote(notes: string | null | undefined, handoverDocumentNote: string): string {
+    const trimmed = notes?.trim();
+    if (!trimmed) return handoverDocumentNote;
+    const index = trimmed.lastIndexOf(HANDOVER_DOCUMENT_MARKER);
+    if (index < 0) {
+      return `${trimmed}\n\n${handoverDocumentNote}`;
+    }
+    return [trimmed.slice(0, index).trim(), handoverDocumentNote].filter(Boolean).join('\n\n');
+  }
+
+  private extractHandoverDocumentLine(notes: string | null | undefined, label: string): string | null {
+    if (!notes) return null;
+    const index = notes.lastIndexOf(HANDOVER_DOCUMENT_MARKER);
+    if (index < 0) return null;
+    const section = notes.slice(index + HANDOVER_DOCUMENT_MARKER.length);
+    const match = section.match(new RegExp(`^${label}:\\s*(.+)$`, 'im'));
+    return match?.[1]?.trim() || null;
+  }
+
   private buildReceiveNote(input: {
     grnNumber: string;
     direction?: string | null;
diff --git a/apps/edr-freight-api/src/scripts/seed-warehouse-export-receive-ready.ts b/apps/edr-freight-api/src/scripts/seed-warehouse-export-receive-ready.ts
new file mode 100644
index 000000000..367b79b44
--- /dev/null
+++ b/apps/edr-freight-api/src/scripts/seed-warehouse-export-receive-ready.ts
@@ -0,0 +1,142 @@
+import 'reflect-metadata';
+import { config } from 'dotenv';
+import { resolve } from 'path';
+
+config({ path: resolve(__dirname, '../../.env') });
+
+import { NestFactory } from '@nestjs/core';
+import { DataSource } from 'typeorm';
+
+import { AppModule } from '../app.module';
+import { Booking } from '../modules/bookings/entities/booking.entity';
+import { BookingContainer } from '../modules/bookings/entities/booking-container.entity';
+import { WarehouseInventory } from '../modules/warehouses/entities/warehouse-inventory.entity';
+import { CargoType } from '../modules/rule-engine/entities/cargo-type.entity';
+import { ContainerType } from '../modules/rule-engine/entities/container-type.entity';
+import { ServiceType } from '../modules/rule-engine/entities/service-type.entity';
+import { Yard } from '../modules/rule-engine/entities/yard.entity';
+
+const BOOKING_REFS = [
+  'WH-EXP-RCV-001',
+  'WH-EXP-RCV-002',
+  'WH-EXP-RCV-003',
+  'WH-EXP-RCV-004',
+  'WH-EXP-RCV-005',
+];
+
+async function main() {
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['error', 'warn', 'log'],
+  });
+
+  try {
+    const dataSource = app.get(DataSource);
+    const yardRepo = dataSource.getRepository(Yard);
+    const serviceTypeRepo = dataSource.getRepository(ServiceType);
+    const cargoTypeRepo = dataSource.getRepository(CargoType);
+    const containerTypeRepo = dataSource.getRepository(ContainerType);
+    const bookingRepo = dataSource.getRepository(Booking);
+    const bookingContainerRepo = dataSource.getRepository(BookingContainer);
+    const inventoryRepo = dataSource.getRepository(WarehouseInventory);
+
+    const originYard =
+      (await yardRepo.findOne({ where: { code: 'MOJO' } })) ??
+      (await yardRepo.findOne({ where: { country: 'Ethiopia' } }));
+    const destinationYard =
+      (await yardRepo.findOne({ where: { code: 'DJIB_PORT' } })) ??
+      (await yardRepo.findOne({ where: { country: 'Djibouti' } }));
+    const serviceType =
+      (await serviceTypeRepo.findOne({ where: { code: 'RAIL_CONTAINER', includesFirstMile: false, isActive: true } })) ??
+      (await serviceTypeRepo.findOne({ where: { includesFirstMile: false, isActive: true } }));
+    const cargoType = await cargoTypeRepo.findOne({ where: { isActive: true } });
+    const containerType =
+      (await containerTypeRepo.findOne({ where: { code: '40FT', isActive: true } })) ??
+      (await containerTypeRepo.findOne({ where: { code: '40', isActive: true } })) ??
+      (await containerTypeRepo.findOne({ where: { sizeFt: 40, isActive: true } })) ??
+      (await containerTypeRepo.findOne({ where: { isActive: true } }));
+
+    const missing = [
+      !originYard ? 'MOJO/Ethiopia origin yard' : '',
+      !destinationYard ? 'DJIB_PORT/Djibouti destination yard' : '',
+      !serviceType ? 'active service type without first mile' : '',
+      !containerType ? 'active container type' : '',
+    ].filter(Boolean);
+
+    if (missing.length) {
+      throw new Error(`Cannot seed warehouse export receive-ready bookings, missing: ${missing.join(', ')}`);
+    }
+
+    let created = 0;
+    let skipped = 0;
+    const now = Date.now();
+
+    for (const [index, reference] of BOOKING_REFS.entries()) {
+      const existing = await bookingRepo.findOne({ where: { reference } });
+      if (existing) {
+        skipped += 1;
+        continue;
+      }
+
+      const containerQuantity = index === 4 ? 2 : 1;
+      const weightKg = 18_000 + index * 1_250 + (containerQuantity - 1) * 9_000;
+      const scheduledDate = new Date(now + index * 60 * 60_000);
+
+      const booking = await bookingRepo.save(
+        bookingRepo.create({
+          reference,
+          originYardId: originYard!.id,
+          destinationYardId: destinationYard!.id,
+          serviceTypeId: serviceType!.id,
+          status: 'PAID',
+          paymentStatus: 'PAID',
+          scheduledDate,
+          contractType: 'SPOT',
+          equipmentReturn: 'TERMINAL',
+          paymentCurrency: 'ETB',
+          totalAmount: 0,
+          isGovernment: false,
+          tradeDirection: 'EXPORT',
+          freightType: 'CONTAINER',
+          cargoTypeId: cargoType?.id ?? null,
+          cargoFreeText: cargoType ? null : `Warehouse export receive-ready cargo ${index + 1}`,
+          cargoTotalWeightVgm: weightKg,
+          schedulingStatus: 'NOT_SCHEDULED',
+        }),
+      );
+
+      await bookingContainerRepo.save(
+        bookingContainerRepo.create({
+          bookingId: booking.id,
+          containerTypeId: containerType!.id,
+          containerNumber: `EDRU${String(730100 + index).padStart(6, '0')}`,
+          containerSize: containerType!.sizeFt ? `${containerType!.sizeFt}ft` : containerType!.code,
+          quantity: containerQuantity,
+          hazardousQuantity: 0,
+          reeferQuantity: 0,
+          vgmPerUnitTons: Number((weightKg / containerQuantity / 1000).toFixed(3)),
+          totalVgmTons: Number((weightKg / 1000).toFixed(3)),
+          wagonsRequired: Math.max(1, containerQuantity * Number(containerType!.wagonsPerUnit ?? 1)),
+          isOverweight: false,
+        }),
+      );
+
+      const inventory = await inventoryRepo.findOne({ where: { bookingId: booking.id } });
+      if (inventory) {
+        throw new Error(`Seed invariant failed: booking ${reference} unexpectedly has warehouse inventory`);
+      }
+
+      created += 1;
+    }
+
+    console.log(`Warehouse export receive-ready seed complete. Created ${created}, skipped ${skipped}.`);
+    console.log(`Booking refs: ${BOOKING_REFS.join(', ')}`);
+    console.log('Open Backoffice Warehouse > Receive for loading > Export / Receive to Warehouse.');
+  } finally {
+    await app.close();
+  }
+}
+
+main().catch((error) => {
+  console.error('Warehouse export receive-ready seed failed:', error);
+  process.exit(1);
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/InventoryDetailModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/InventoryDetailModal.tsx
index b0b864e4d..c888253f1 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/InventoryDetailModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/InventoryDetailModal.tsx
@@ -23,11 +23,20 @@ function DetailRow({ label, value }: { label: string; value: React.ReactNode })
   );
 }
 
+const noteLineValue = (notes: string | null | undefined, label: string) => {
+  const match = notes?.match(new RegExp(`^${label}:\\s*(.+)$`, 'im'));
+  return match?.[1]?.trim() ?? '';
+};
+
 export function InventoryDetailModal({ opened, onClose, item }: InventoryDetailModalProps) {
   const bookingReference = item?.booking?.reference ?? '-';
+  const handoverReference = item?.handoverDocumentReference ?? noteLineValue(item?.notes, 'Handover Reference');
+  const handoverDate = item?.handoverDocumentDate ?? noteLineValue(item?.notes, 'Generated At');
   const inventorySummary = [
     item?.status?.replace(/_/g, ' '),
+    item?.grnNumber ? `GRN ${item.grnNumber}` : null,
     item?.releaseOrderReference ? `Release ${item.releaseOrderReference}` : null,
+    handoverReference ? `Handover ${handoverReference}` : null,
     item?.warehouse ? `${item.warehouse.name} (${item.warehouse.code})` : null,
   ]
     .filter(Boolean)
@@ -61,11 +70,13 @@ export function InventoryDetailModal({ opened, onClose, item }: InventoryDetailM
           <Divider label="Booking & item" labelPosition="left" />
           <SimpleGrid cols={{ base: 1, sm: 3 }}>
             <DetailRow label="Booking reference" value={bookingReference} />
+            <DetailRow label="GRN" value={item.grnNumber ?? '-'} />
             <DetailRow label="Booking status" value={item.booking?.status ?? '-'} />
             <DetailRow label="Payment status" value={item.booking?.paymentStatus ?? '-'} />
             <DetailRow label="Trade direction" value={item.booking?.tradeDirection ?? '-'} />
             <DetailRow label="Inventory status" value={item.status.replace(/_/g, ' ')} />
             <DetailRow label="Release reference" value={item.releaseOrderReference ?? '-'} />
+            <DetailRow label="Handover reference" value={handoverReference || '-'} />
             <DetailRow label="Quantity" value={formatNumber(item.quantity)} />
             <DetailRow label="Weight" value={`${formatNumber(item.weight)} kg`} />
             <DetailRow label="Volume" value={item.volume == null ? '-' : formatNumber(item.volume)} />
@@ -83,6 +94,7 @@ export function InventoryDetailModal({ opened, onClose, item }: InventoryDetailM
             <DetailRow label="Dispatched" value={formatDate(item.dispatchedAt)} />
             <DetailRow label="Ready for pickup" value={formatDate(item.readyForPickupAt)} />
             <DetailRow label="Released" value={formatDate(item.releaseDate)} />
+            <DetailRow label="Handover generated" value={formatDate(handoverDate)} />
             <DetailRow label="Delivered" value={formatDate(item.deliveredAt)} />
             <DetailRow label="Release reference" value={item.releaseOrderReference ?? '-'} />
           </SimpleGrid>
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
index eb320d78b..924d4456e 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
@@ -1,4 +1,4 @@
-import { Fragment, useEffect, useMemo, useState } from 'react';
+import { Fragment, useEffect, useMemo, useState, type MouseEvent } from 'react';
 import {
   ActionIcon,
   Alert,
@@ -79,6 +79,45 @@ interface ReceiveInventoryModalProps {
   onReceived?: () => void;
 }
 
+function GrnDocumentButton({ inventoryId, grnNumber }: { inventoryId: string; grnNumber?: string | null }) {
+  const { toast } = useToast();
+  const [loading, setLoading] = useState(false);
+
+  const openDocument = async (event: MouseEvent<HTMLButtonElement>) => {
+    event.stopPropagation();
+    if (!grnNumber) {
+      toast({ variant: 'destructive', title: 'GRN document unavailable', description: 'This item has no GRN number yet.' });
+      return;
+    }
+    setLoading(true);
+    const pdfWindow = window.open('', '_blank');
+    try {
+      const response = await warehouseService.downloadGrnDocument(inventoryId);
+      const opened = openPdfBlob(response.data, `grn-${grnNumber}.pdf`, pdfWindow);
+      toast({ title: opened ? 'GRN document opened' : 'GRN document downloaded' });
+    } catch (error) {
+      pdfWindow?.close();
+      toast({ variant: 'destructive', title: 'GRN document failed', description: extractErrorMessage(error) });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      size="compact-xs"
+      variant="subtle"
+      color="teal"
+      leftSection={<FileText size={12} />}
+      disabled={!grnNumber}
+      loading={loading}
+      onClick={openDocument}
+    >
+      {grnNumber ?? 'No GRN'}
+    </Button>
+  );
+}
+
 interface Location {
   warehouseId: string;
   yardId: string;
@@ -620,11 +659,13 @@ function EligibleTab({
   const { toast } = useToast();
   const qc = useQueryClient();
   const { data: allRows = [], isLoading } = useQuery(
-    api.warehouses.eligibleBookings.queryOptions({ enabled }),
+    api.warehouses.eligibleBookings.queryOptions({
+      input: { direction },
+      enabled,
+    }),
   );
   const rows = useMemo(() => allRows.filter((r) => r.direction === direction), [allRows, direction]);
   const bulkReceive = useMutation(api.warehouses.bulkReceive.mutationOptions());
-  const loadPassed = useMutation(api.warehouses.loadPassedExport.mutationOptions());
   const requestFirstMile = useMutation({
     mutationFn: (reference: string) => firstMileService.accept(reference),
     onSuccess: () => {
@@ -782,10 +823,24 @@ function EligibleTab({
       return;
     }
     const { form, lockedFields, packagingFreightType: nextPackagingFreightType } = truckEntranceFromBookings(selectedRows);
+    const totalContainerQuantity = selectedRows.reduce(
+      (sum, row) => sum + Number(row.containerQuantity ?? 0),
+      0,
+    );
+    const normalizedForm =
+      nextPackagingFreightType === 'CONTAINER' && totalContainerQuantity > 0
+        ? {
+            ...form,
+            unitCount: totalContainerQuantity,
+          }
+        : form;
     setPendingReceiveIds(filteredIds);
     setReceivedAt(new Date().toISOString());
-    setTruckForm(form);
-    setLockedTruckFields(lockedFields);
+    setTruckForm(normalizedForm);
+    setLockedTruckFields({
+      ...lockedFields,
+      unitCount: nextPackagingFreightType === 'CONTAINER' && totalContainerQuantity > 0,
+    });
     setPackagingFreightType(nextPackagingFreightType);
     setTruckOpen(true);
   };
@@ -798,18 +853,6 @@ function EligibleTab({
     await receiveBookings(pendingReceiveIds, toTruckEntrancePayload(truckForm));
   };
 
-  const loadPassedExport = async () => {
-    try {
-      const r = await loadPassed.mutateAsync(undefined);
-      toast({
-        title: `${r.loadedCount} loaded`,
-        description: r.skippedCount ? `${r.skippedCount} skipped — inspection not passed` : undefined,
-      });
-      onChanged?.();
-    } catch (error) {
-      toast({ variant: 'destructive', title: 'Load failed', description: extractErrorMessage(error) });
-    }
-  };
 
   return (
     <Stack gap="sm" mt="sm">
@@ -828,18 +871,6 @@ function EligibleTab({
           Selected: <b>{selected.size}</b> / {statusFilteredRows.length} eligible
         </Text>
         <Group gap="xs">
-          {direction === 'EXPORT' && (
-            <Button
-              size="compact-sm"
-              variant="light"
-              color="teal"
-              leftSection={<Truck size={14} />}
-              loading={loadPassed.isPending}
-              onClick={loadPassedExport}
-            >
-              Load Passed Export Items
-            </Button>
-          )}
           <Button
             size="compact-sm"
             color={direction === 'EXPORT' ? 'edr-green' : undefined}
@@ -849,7 +880,7 @@ function EligibleTab({
             loading={bulkReceive.isPending}
             onClick={() => openTruckReceive(selected.size > 0 ? [...selected] : selectableRows.map((r) => r.id))}
           >
-            {direction === 'EXPORT' ? 'Receive to Warehouse' : 'Receive All to Warehouse'}
+            {direction === 'EXPORT' ? 'Receive All for Loading' : 'Receive All to Warehouse'}
           </Button>
           <Button
             size="compact-sm"
@@ -858,7 +889,7 @@ function EligibleTab({
             loading={bulkReceive.isPending}
             onClick={() => openTruckReceive([...selected])}
           >
-            Receive Selected
+            {direction === 'EXPORT' ? 'Receive Selected for Loading' : 'Receive Selected'}
           </Button>
         </Group>
       </Group>
@@ -1000,7 +1031,7 @@ function EligibleTab({
                         loading={bulkReceive.isPending}
                         onClick={() => openTruckReceive([r.id])}
                       >
-                        {canReceive ? 'Receive to Warehouse' : 'Await First Mile'}
+                        {canReceive ? (direction === 'EXPORT' ? 'Receive for Loading' : 'Receive to Warehouse') : 'Await First Mile'}
                       </Button>
                     )}
                   </Table.Td>
@@ -1015,7 +1046,7 @@ function EligibleTab({
       <Modal
         opened={truckOpen}
         onClose={() => setTruckOpen(false)}
-        title="Receive to Warehouse"
+        title={direction === 'EXPORT' ? 'Receive for Loading' : 'Receive to Warehouse'}
         centered
         size="lg"
       >
@@ -1175,6 +1206,7 @@ function ExportReceivedTab({ enabled, onChanged }: { enabled: boolean; onChanged
                   />
                 </Table.Th>
                 <Table.Th>Booking Ref</Table.Th>
+                <Table.Th>GRN</Table.Th>
                 <Table.Th>Booking ID</Table.Th>
                 <Table.Th>Customer ID</Table.Th>
                 <Table.Th>Customer Name</Table.Th>
@@ -1201,7 +1233,13 @@ function ExportReceivedTab({ enabled, onChanged }: { enabled: boolean; onChanged
                       />
                     </Table.Td>
                     <Table.Td>
-                      <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                      <Stack gap={2}>
+                        <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                        <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
+                      </Stack>
+                    </Table.Td>
+                    <Table.Td>
+                      <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
                     </Table.Td>
                     <Table.Td>
                       <Text size="xs" c="dimmed">{r.bookingId ? `${r.bookingId.slice(0, 8)}…` : '—'}</Text>
@@ -1322,6 +1360,7 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
                   />
                 </Table.Th>
                 <Table.Th>Booking Ref</Table.Th>
+                <Table.Th>GRN</Table.Th>
                 <Table.Th>Booking ID</Table.Th>
                 <Table.Th>Customer ID</Table.Th>
                 <Table.Th>Customer Name</Table.Th>
@@ -1344,7 +1383,13 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
                     />
                   </Table.Td>
                   <Table.Td>
-                    <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                    <Stack gap={2}>
+                      <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                      <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
+                    </Stack>
+                  </Table.Td>
+                  <Table.Td>
+                    <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
                   </Table.Td>
                   <Table.Td>
                     <Text size="xs" c="dimmed">{r.bookingId ? `${r.bookingId.slice(0, 8)}…` : '—'}</Text>
@@ -1492,6 +1537,7 @@ function LoadedExportTab({
                   </Table.Th>
                 )}
                 <Table.Th>Booking Ref</Table.Th>
+                <Table.Th>GRN</Table.Th>
                 <Table.Th>Booking ID</Table.Th>
                 <Table.Th>Customer ID</Table.Th>
                 <Table.Th>Customer Name</Table.Th>
@@ -1516,7 +1562,13 @@ function LoadedExportTab({
                     </Table.Td>
                   )}
                   <Table.Td>
-                    <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                    <Stack gap={2}>
+                      <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                      <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
+                    </Stack>
+                  </Table.Td>
+                  <Table.Td>
+                    <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
                   </Table.Td>
                   <Table.Td>
                     <Text size="xs" c="dimmed">{r.bookingId ? `${r.bookingId.slice(0, 8)}…` : '—'}</Text>
@@ -1866,12 +1918,15 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
       bookingId: row.bookingId,
       quantity: 1,
       weight: Number(row.weight) || 0,
+      grnNumber: row.grnNumber,
       status: row.currentStatus,
       arrivedAt: row.arrivalTime,
       unloadedAt: row.arrivalTime,
       inspectionStatus: row.inspectionStatus,
       releaseDate: row.releaseDate,
       releaseOrderReference: row.releaseOrderReference,
+      handoverDocumentReference: row.handoverDocumentReference,
+      handoverDocumentDate: row.handoverDocumentDate,
       deliveredAt: row.deliveredAt,
       booking: row.bookingId
         ? {
@@ -1902,6 +1957,7 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
     try {
       const response = await warehouseService.downloadHandoverDocument(row.id);
       openPdfBlob(response.data, `handover-${row.bookingReference ?? row.id}.pdf`, pdfWindow);
+      void qc.invalidateQueries({ queryKey: ['warehouse-inventory'] });
     } catch (error) {
       pdfWindow?.close();
       toast({ variant: 'destructive', title: 'Handover document failed', description: extractErrorMessage(error) });
@@ -1910,6 +1966,20 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
     }
   };
 
+  const openReleaseDocument = async (row: ImportUnloadedItem) => {
+    setBusyId(row.id);
+    const pdfWindow = window.open('', '_blank');
+    try {
+      const response = await warehouseService.downloadReleaseDocument(row.id);
+      openPdfBlob(response.data, `release-${row.bookingReference ?? row.id}.pdf`, pdfWindow);
+    } catch (error) {
+      pdfWindow?.close();
+      toast({ variant: 'destructive', title: 'Exit paper failed', description: extractErrorMessage(error) });
+    } finally {
+      setBusyId(null);
+    }
+  };
+
   return (
     <Stack gap="sm" mt="sm">
       <Group justify="space-between">
@@ -1959,6 +2029,7 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
                 </Table.Th>
                 <Table.Th>Booking ID</Table.Th>
                 <Table.Th>Booking Ref</Table.Th>
+                <Table.Th>GRN</Table.Th>
                 <Table.Th>Customer ID</Table.Th>
                 <Table.Th>Customer Name</Table.Th>
                 <Table.Th>Arrival Time</Table.Th>
@@ -1987,7 +2058,13 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
                     <Text size="xs" c="dimmed">{r.bookingId ? `${r.bookingId.slice(0, 8)}…` : '—'}</Text>
                   </Table.Td>
                   <Table.Td>
-                    <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                    <Stack gap={2}>
+                      <Text size="sm" fw={600}>{r.bookingReference ?? '—'}</Text>
+                      <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
+                    </Stack>
+                  </Table.Td>
+                  <Table.Td>
+                    <GrnDocumentButton inventoryId={r.id} grnNumber={r.grnNumber} />
                   </Table.Td>
                   <Table.Td>
                     <Text size="xs" c="dimmed">{r.customerId ? `${r.customerId.slice(0, 8)}…` : '—'}</Text>
@@ -2049,7 +2126,7 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
                             color="yellow"
                             onClick={() => setReleaseItem(toInventoryItem(r))}
                           >
-                            Truck Arrival
+                            {r.releaseOrderReference ? 'Truck Leaving' : 'Truck Arrival'}
                           </Button>
                         </>
                       )}
@@ -2064,6 +2141,18 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
                           Dispatch
                         </Button>
                       )}
+                      {r.currentStatus === 'READY_FOR_PICKUP' && r.releaseDate && (
+                        <Button
+                          size="compact-xs"
+                          variant="light"
+                          color="orange"
+                          leftSection={<FileText size={14} />}
+                          loading={busyId === r.id}
+                          onClick={() => openReleaseDocument(r)}
+                        >
+                          Exit Paper
+                        </Button>
+                      )}
                       {r.currentStatus === 'READY_FOR_PICKUP' && r.releaseDate && (
                         <Button
                           size="compact-xs"
@@ -2082,7 +2171,7 @@ function ImportUnloadedQueueTab({ enabled }: { enabled: boolean }) {
                           leftSection={<FileText size={14} />}
                           onClick={() => openHandoverDocument(r)}
                         >
-                          Handover
+                          {r.handoverDocumentReference ? 'View Handover' : 'Handover'}
                         </Button>
                       )}
                       <Button size="compact-xs" variant="light" color="orange" onClick={() => setInspectId(r.id)}>
@@ -2398,7 +2487,12 @@ function ExportWarehouseTabs({
   onChanged?: () => void;
 }) {
   const [activeTab, setActiveTab] = useState<ExportWarehouseTab>('receive-queue');
-  const { data: eligibleRows = [] } = useQuery(api.warehouses.eligibleBookings.queryOptions({ enabled }));
+  const { data: eligibleRows = [] } = useQuery(
+    api.warehouses.eligibleBookings.queryOptions({
+      input: { direction: 'EXPORT' },
+      enabled,
+    }),
+  );
   const { data: receivedRows = [] } = useQuery(api.warehouses.receivedExport.queryOptions({ enabled }));
   const { data: readyRows = [] } = useQuery(api.warehouses.readyToLoadExport.queryOptions({ enabled }));
   const { data: loadedRows = [] } = useQuery(api.warehouses.loadedExport.queryOptions({ enabled }));
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
index ec7ca6907..be49e527b 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { Alert, Button, Group, Modal, NumberInput, Select, Stack, Text, TextInput } from '@mantine/core';
+import { Alert, Button, Group, Modal, NumberInput, Select, SimpleGrid, Stack, Text, TextInput } from '@mantine/core';
 import { Info, Scale } from 'lucide-react';
 
 import { useMutation } from '@tanstack/react-query';
@@ -46,6 +46,77 @@ const toIsoDateTime = (value: string) => {
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
 };
 
+const toLocalDateTimeInput = (value?: string | null) => {
+  if (!value) return '';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return '';
+  const offsetMs = date.getTimezoneOffset() * 60_000;
+  return new Date(date.getTime() - offsetMs).toISOString().slice(0, 16);
+};
+
+const generateReleaseReference = (item: WarehouseInventoryItem | null) => {
+  const bookingReference = item?.booking?.reference;
+  if (bookingReference) return `REL-${bookingReference.replace(/^BK-?/i, '')}`;
+  if (item?.bookingId) return `REL-${item.bookingId.replace(/-/g, '').slice(0, 8).toUpperCase()}`;
+  return '';
+};
+
+const lineValue = (notes: string | null | undefined, label: string) => {
+  const match = notes?.match(new RegExp(`^${label}:\\s*(.+)$`, 'im'));
+  return match?.[1]?.trim() ?? '';
+};
+
+const lineNumber = (notes: string | null | undefined, label: string): number | '' => {
+  const value = lineValue(notes, label).replace(/\s*kg$/i, '');
+  if (!value) return '';
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : '';
+};
+
+const splitContainerNumbers = (value: string | null | undefined) =>
+  (value ?? '')
+    .split(/[,;\n]+/)
+    .map((number) => number.trim())
+    .filter(Boolean);
+
+const getItemContainerNumber = (item: WarehouseInventoryItem | null) =>
+  (item as (WarehouseInventoryItem & { containerNumber?: string | null }) | null)?.containerNumber ?? '';
+
+const isContainerInventory = (item: WarehouseInventoryItem | null, containerCount: number) => {
+  const freightType = (item as (WarehouseInventoryItem & { booking?: { freightType?: string | null } | null }) | null)
+    ?.booking?.freightType;
+  return Boolean(item?.containerId || containerCount > 0 || freightType === 'CONTAINER');
+};
+
+const initialContainerNumbers = (item: WarehouseInventoryItem | null, savedContainerNumber: string) => {
+  const savedNumbers = splitContainerNumbers(savedContainerNumber);
+  const itemNumbers = splitContainerNumbers(getItemContainerNumber(item));
+  const sourceNumbers = savedNumbers.length ? savedNumbers : itemNumbers;
+  const quantityCount = isContainerInventory(item, sourceNumbers.length) ? Number(item?.quantity ?? 0) : 0;
+  const expectedCount = Math.max(1, sourceNumbers.length, quantityCount);
+  return Array.from({ length: expectedCount }, (_, index) => sourceNumbers[index] ?? '');
+};
+
+const parseInspectionNote = (notes: string | null | undefined) => {
+  const marker = '[Exit Inspection]';
+  const index = notes?.lastIndexOf(marker) ?? -1;
+  const note = index >= 0 ? notes?.slice(index + marker.length) : notes;
+  return {
+    truckPlateNumber: lineValue(note, 'Truck Plate'),
+    trailerPlateNumber: lineValue(note, 'Trailer Plate'),
+    driverName: lineValue(note, 'Driver'),
+    driverLicense: lineValue(note, 'Driver License'),
+    driverPhone: lineValue(note, 'Driver Phone'),
+    truckType: lineValue(note, 'Truck Type'),
+    containerNumber: lineValue(note, 'Container Number'),
+    gateInTime: toLocalDateTimeInput(lineValue(note, 'Gate In Time')),
+    tareWeight: lineNumber(note, 'Tare Weight'),
+    grossWeight: lineNumber(note, 'Gross Weight'),
+    netWeight: lineNumber(note, 'Net Weight'),
+    gateOutTime: toLocalDateTimeInput(lineValue(note, 'Gate Out Time')),
+  };
+};
+
 export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalProps) {
   const { toast } = useToast();
   const releaseMutation = useMutation(api.warehouses.release.mutationOptions());
@@ -56,7 +127,7 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
   const [driverLicense, setDriverLicense] = useState('');
   const [driverPhone, setDriverPhone] = useState('');
   const [truckType, setTruckType] = useState('');
-  const [containerNumber, setContainerNumber] = useState('');
+  const [containerNumbers, setContainerNumbers] = useState<string[]>(['']);
   const [gateInTime, setGateInTime] = useState('');
   const [tareWeight, setTareWeight] = useState<number | ''>('');
   const [grossWeight, setGrossWeight] = useState<number | ''>('');
@@ -66,26 +137,32 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
 
   useEffect(() => {
     if (opened) {
-      setReference(item?.releaseOrderReference ?? '');
-      setTruckPlateNumber('');
-      setTrailerPlateNumber('');
-      setDriverName('');
-      setDriverLicense('');
-      setDriverPhone('');
-      setTruckType('');
-      setContainerNumber('');
-      setGateInTime('');
-      setTareWeight('');
-      setGrossWeight('');
-      setNetWeight(item?.weight != null ? Number(item.weight) : '');
-      setGateOutTime('');
+      const inspection = parseInspectionNote(item?.notes);
+      setReference(item?.releaseOrderReference ?? generateReleaseReference(item));
+      setTruckPlateNumber(inspection.truckPlateNumber);
+      setTrailerPlateNumber(inspection.trailerPlateNumber);
+      setDriverName(inspection.driverName);
+      setDriverLicense(inspection.driverLicense);
+      setDriverPhone(inspection.driverPhone);
+      setTruckType(inspection.truckType);
+      setContainerNumbers(initialContainerNumbers(item, inspection.containerNumber));
+      setGateInTime(inspection.gateInTime);
+      setTareWeight(inspection.tareWeight);
+      setGrossWeight(inspection.grossWeight);
+      setNetWeight(item?.weight == null ? inspection.netWeight : Number(item.weight));
+      setGateOutTime(inspection.gateOutTime);
     }
   }, [opened, item]);
 
+  const savedInspection = parseInspectionNote(item?.notes);
+  const isExitStep = savedInspection.tareWeight !== '';
+  const isEntranceLocked = isExitStep;
+  const systemNetWeight = item?.weight == null ? netWeight : Number(item.weight);
   const computedNetWeight =
     tareWeight !== '' && grossWeight !== '' ? Number((Number(grossWeight) - Number(tareWeight)).toFixed(3)) : null;
   const weightMismatch =
-    computedNetWeight != null && netWeight !== '' && Math.abs(Number(netWeight) - computedNetWeight) > 0.001;
+    computedNetWeight != null && systemNetWeight !== '' && Math.abs(Number(systemNetWeight) - computedNetWeight) > 0.001;
+  const title = isExitStep ? 'Customer truck leaving and exit weighing' : 'Customer truck arrival weighing';
 
   const handleSubmit = async () => {
     if (!item) return;
@@ -93,11 +170,19 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
       toast({ variant: 'destructive', title: 'Truck plate and driver name are required' });
       return;
     }
-    if (tareWeight === '' || grossWeight === '') {
-      toast({ variant: 'destructive', title: 'Tare and gross weight are required' });
+    if (!gateInTime || tareWeight === '') {
+      toast({ variant: 'destructive', title: 'Gate in time and tare weight are required' });
       return;
     }
-    if (weightMismatch) {
+    if (isExitStep && (!gateOutTime || grossWeight === '')) {
+      toast({ variant: 'destructive', title: 'Gate out time and gross weight are required' });
+      return;
+    }
+    if (isExitStep && systemNetWeight === '') {
+      toast({ variant: 'destructive', title: 'System recorded net weight is missing' });
+      return;
+    }
+    if (isExitStep && weightMismatch) {
       toast({
         variant: 'destructive',
         title: 'Weight mismatch',
@@ -105,7 +190,7 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
       });
       return;
     }
-    const pdfWindow = window.open('', '_blank');
+    const pdfWindow = isExitStep ? window.open('', '_blank') : null;
     try {
       const released = await releaseMutation.mutateAsync({
         id: item.id,
@@ -119,14 +204,22 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
           driverLicense: driverLicense.trim() || undefined,
           driverPhone: driverPhone.trim() || undefined,
           truckType: truckType.trim() || undefined,
-          containerNumber: containerNumber.trim() || undefined,
+          containerNumber: containerNumbers.map((number) => number.trim()).filter(Boolean).join(', ') || undefined,
           gateInTime: toIsoDateTime(gateInTime),
           tareWeight: Number(tareWeight),
-          grossWeight: Number(grossWeight),
-          netWeight: netWeight === '' ? computedNetWeight ?? undefined : Number(netWeight),
-          gateOutTime: toIsoDateTime(gateOutTime),
+          grossWeight: grossWeight === '' ? undefined : Number(grossWeight),
+          netWeight: isExitStep && systemNetWeight !== '' ? Number(systemNetWeight) : undefined,
+          gateOutTime: isExitStep ? toIsoDateTime(gateOutTime) : undefined,
         },
       });
+      if (!isExitStep) {
+        toast({
+          title: 'Truck arrival saved',
+          description: `${released.releaseOrderReference ?? reference} is ready for exit weighing.`,
+        });
+        onClose();
+        return;
+      }
       setDownloading(true);
       const response = await warehouseService.downloadReleaseDocument(item.id);
       const blob = response.data;
@@ -148,20 +241,27 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
   };
 
   return (
-    <Modal opened={opened} onClose={onClose} title="Customer truck arrival and exit weighing" centered size="lg">
+    <Modal opened={opened} onClose={onClose} title={title} centered size="lg">
       <Stack gap="md">
         <Alert icon={<Info size={16} />} color="orange" variant="light">
-          <Text size="sm">
-            Register the customer truck and driver at arrival, record tare weight, then record gross
-            weight at exit after loading. Gate clearance is blocked when recorded net weight does not
-            equal gross weight minus tare weight.
-          </Text>
+          {isExitStep ? (
+            <Text size="sm">
+              Record the truck leaving time and gross weight. The system recorded net weight is locked,
+              and the exit paper is generated only when it equals gross weight minus tare weight.
+            </Text>
+          ) : (
+            <Text size="sm">
+              Register the customer truck and driver at arrival, then save gate in time and tare weight.
+              Reopen this form when the truck is leaving to complete the exit weighing.
+            </Text>
+          )}
         </Alert>
         <TextInput
           label="Release document reference"
           placeholder="e.g. REL-2026-001"
           value={reference}
           onChange={(e) => setReference(e.currentTarget.value)}
+          readOnly={isEntranceLocked}
         />
         <Select
           label="Registered first / last-mile truck"
@@ -169,6 +269,7 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
           searchable
           clearable
           data={REGISTERED_FIRST_LAST_MILE_TRUCKS}
+          disabled={isEntranceLocked}
           value={REGISTERED_FIRST_LAST_MILE_TRUCKS.some((truck) => truck.value === truckPlateNumber) ? truckPlateNumber : null}
           onChange={(value) => {
             const truck = REGISTERED_FIRST_LAST_MILE_TRUCKS.find((row) => row.value === value);
@@ -182,35 +283,53 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
             required
             value={truckPlateNumber}
             onChange={(e) => setTruckPlateNumber(e.currentTarget.value)}
+            readOnly={isEntranceLocked}
           />
           <TextInput
             label="Trailer plate number"
             value={trailerPlateNumber}
             onChange={(e) => setTrailerPlateNumber(e.currentTarget.value)}
+            readOnly={isEntranceLocked}
           />
         </Group>
         <Group grow>
-          <TextInput label="Driver name" required value={driverName} onChange={(e) => setDriverName(e.currentTarget.value)} />
-          <TextInput label="Driver license" value={driverLicense} onChange={(e) => setDriverLicense(e.currentTarget.value)} />
+          <TextInput label="Driver name" required value={driverName} onChange={(e) => setDriverName(e.currentTarget.value)} readOnly={isEntranceLocked} />
+          <TextInput label="Driver license" value={driverLicense} onChange={(e) => setDriverLicense(e.currentTarget.value)} readOnly={isEntranceLocked} />
         </Group>
         <Group grow>
-          <TextInput label="Driver phone" value={driverPhone} onChange={(e) => setDriverPhone(e.currentTarget.value)} />
-          <TextInput label="Truck type" value={truckType} onChange={(e) => setTruckType(e.currentTarget.value)} />
+          <TextInput label="Driver phone" value={driverPhone} onChange={(e) => setDriverPhone(e.currentTarget.value)} readOnly={isEntranceLocked} />
+          <TextInput label="Truck type" value={truckType} onChange={(e) => setTruckType(e.currentTarget.value)} readOnly={isEntranceLocked} />
         </Group>
         <Group grow>
-          <TextInput label="Container number" value={containerNumber} onChange={(e) => setContainerNumber(e.currentTarget.value)} />
-          <TextInput label="Gate in time" type="datetime-local" value={gateInTime} onChange={(e) => setGateInTime(e.currentTarget.value)} />
+          <Stack gap={6}>
+            <SimpleGrid cols={containerNumbers.length > 1 ? 2 : 1} spacing="sm">
+              {containerNumbers.map((containerNumber, index) => (
+                <TextInput
+                  key={index}
+                  label={containerNumbers.length > 1 ? `Container number ${index + 1}` : 'Container number'}
+                  value={containerNumber}
+                  onChange={(e) =>
+                    setContainerNumbers((numbers) =>
+                      numbers.map((number, numberIndex) => (numberIndex === index ? e.currentTarget.value : number)),
+                    )
+                  }
+                  readOnly={isEntranceLocked}
+                />
+              ))}
+            </SimpleGrid>
+          </Stack>
+          <TextInput label="Gate in time" type="datetime-local" value={gateInTime} onChange={(e) => setGateInTime(e.currentTarget.value)} readOnly={isEntranceLocked} />
         </Group>
         <Group grow>
-          <NumberInput label="Tare weight (kg)" required min={0} value={tareWeight} onChange={(v) => setTareWeight(v === '' ? '' : Number(v))} />
-          <NumberInput label="Gross weight (kg)" required min={0} value={grossWeight} onChange={(v) => setGrossWeight(v === '' ? '' : Number(v))} />
-          <NumberInput label="Recorded net weight (kg)" min={0} value={netWeight} onChange={(v) => setNetWeight(v === '' ? '' : Number(v))} />
+          <NumberInput label="Tare weight (kg)" required min={0} value={tareWeight} onChange={(v) => setTareWeight(v === '' ? '' : Number(v))} readOnly={isEntranceLocked} />
+          <NumberInput label="Gross weight (kg)" required={isExitStep} min={0} value={grossWeight} onChange={(v) => setGrossWeight(v === '' ? '' : Number(v))} disabled={!isExitStep} />
+          <NumberInput label="Recorded net weight (system kg)" min={0} value={systemNetWeight} readOnly />
         </Group>
         <Group justify="space-between">
           <Text size="sm" c={weightMismatch ? 'red' : 'dimmed'}>
             Computed net: <b>{computedNetWeight == null ? '-' : `${computedNetWeight.toLocaleString()} kg`}</b>
           </Text>
-          <TextInput label="Gate out time" type="datetime-local" value={gateOutTime} onChange={(e) => setGateOutTime(e.currentTarget.value)} />
+          <TextInput label="Gate out time" type="datetime-local" value={gateOutTime} onChange={(e) => setGateOutTime(e.currentTarget.value)} disabled={!isExitStep} />
         </Group>
         {weightMismatch && (
           <Alert icon={<Scale size={16} />} color="red" variant="light">
@@ -225,7 +344,7 @@ export function ReleaseOrderModal({ opened, onClose, item }: ReleaseOrderModalPr
             Cancel
           </Button>
           <Button color="orange" onClick={handleSubmit} loading={releaseMutation.isPending || downloading}>
-            Save Truck Arrival & View Exit Paper
+            {isExitStep ? 'Save Truck Leaving & View Exit Paper' : 'Save Truck Arrival'}
           </Button>
         </Group>
       </Stack>
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/WarehouseInventoryTable.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/WarehouseInventoryTable.tsx
index aa2b3fd60..b1670fa56 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/WarehouseInventoryTable.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/WarehouseInventoryTable.tsx
@@ -1,13 +1,17 @@
+import { useState, type MouseEvent } from 'react';
 import { ActionIcon, Badge, Button, Checkbox, Group, Table, Text, Tooltip } from '@mantine/core';
 import { ArrowRightLeft, ClipboardList, Coins, Eye, FileText, History, MapPin } from 'lucide-react';
 
+import { useToast } from '@/hooks/use-toast';
+import { warehouseService } from '@/services/warehouse.service';
 import {
   getNextInventoryAction,
   type InventoryAction,
   type WarehouseInventoryItem,
 } from '@/types/warehouse';
 import { InventoryStatusBadge } from './badges';
-import { formatDate, formatNumber, humanizeEnum } from './options';
+import { extractErrorMessage, formatDate, formatNumber, humanizeEnum } from './options';
+import { openPdfBlob } from './pdf';
 
 interface WarehouseInventoryTableProps {
   items: WarehouseInventoryItem[];
@@ -46,6 +50,56 @@ const actionColor: Record<InventoryAction, string> = {
   deliver: 'green',
 };
 
+const releaseActionLabel = (item: WarehouseInventoryItem) =>
+  item.releaseOrderReference ? 'Truck Leaving' : 'Truck Arrival';
+
+const noteLineValue = (notes: string | null | undefined, label: string) => {
+  const match = notes?.match(new RegExp(`^${label}:\\s*(.+)$`, 'im'));
+  return match?.[1]?.trim() ?? '';
+};
+
+const handoverDocumentReference = (item: WarehouseInventoryItem) =>
+  item.handoverDocumentReference ?? noteLineValue(item.notes, 'Handover Reference');
+
+function GrnDocumentButton({ item }: { item: WarehouseInventoryItem }) {
+  const { toast } = useToast();
+  const [loading, setLoading] = useState(false);
+
+  const openDocument = async (event: MouseEvent<HTMLButtonElement>) => {
+    event.stopPropagation();
+    if (!item.grnNumber) {
+      toast({ variant: 'destructive', title: 'GRN document unavailable', description: 'This item has no GRN number yet.' });
+      return;
+    }
+    setLoading(true);
+    const pdfWindow = window.open('', '_blank');
+    try {
+      const response = await warehouseService.downloadGrnDocument(item.id);
+      const opened = openPdfBlob(response.data, `grn-${item.grnNumber}.pdf`, pdfWindow);
+      toast({ title: opened ? 'GRN document opened' : 'GRN document downloaded' });
+    } catch (error) {
+      pdfWindow?.close();
+      toast({ variant: 'destructive', title: 'GRN document failed', description: extractErrorMessage(error) });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      size="compact-xs"
+      variant="subtle"
+      color="teal"
+      leftSection={<FileText size={12} />}
+      disabled={!item.grnNumber}
+      loading={loading}
+      onClick={openDocument}
+    >
+      {item.grnNumber ?? 'No GRN'}
+    </Button>
+  );
+}
+
 export function WarehouseInventoryTable({
   items,
   busyId,
@@ -90,6 +144,7 @@ export function WarehouseInventoryTable({
               </Table.Th>
             )}
             <Table.Th>Booking</Table.Th>
+            <Table.Th>GRN</Table.Th>
             <Table.Th>Facility</Table.Th>
             <Table.Th>Warehouse</Table.Th>
             <Table.Th>Yard</Table.Th>
@@ -111,6 +166,7 @@ export function WarehouseInventoryTable({
               item.inspectionStatus === 'PASSED' &&
               Boolean(item.bookingId) &&
               (!item.booking?.tradeDirection || item.booking.tradeDirection === 'IMPORT');
+            const handoverReference = handoverDocumentReference(item);
 
             return (
               <Table.Tr key={item.id}>
@@ -136,6 +192,9 @@ export function WarehouseInventoryTable({
                     </Text>
                   )}
                 </Table.Td>
+                <Table.Td>
+                  <GrnDocumentButton item={item} />
+                </Table.Td>
                 <Table.Td>{item.warehouse?.facility?.name ?? '-'}</Table.Td>
                 <Table.Td>{item.warehouse?.code ?? '-'}</Table.Td>
                 <Table.Td>{item.yard?.code ?? '-'}</Table.Td>
@@ -170,7 +229,7 @@ export function WarehouseInventoryTable({
                         loading={busy}
                         onClick={() => onAdvance(item, nextAction)}
                       >
-                        {nextAction === 'release' ? 'Truck Arrival' : humanizeEnum(nextAction.replace(/-/g, '_'))}
+                        {nextAction === 'release' ? releaseActionLabel(item) : humanizeEnum(nextAction.replace(/-/g, '_'))}
                       </Button>
                     )}
                     {item.status === 'READY_FOR_PICKUP' && (
@@ -224,7 +283,10 @@ export function WarehouseInventoryTable({
                       </Tooltip>
                     )}
                     {onHandoverDocument && canGenerateHandover && (
-                      <Tooltip label="Generate customer handover document" withArrow>
+                      <Tooltip
+                        label={handoverReference ? `View handover document ${handoverReference}` : 'Generate customer handover document'}
+                        withArrow
+                      >
                         <ActionIcon variant="subtle" color="teal" onClick={() => onHandoverDocument(item)}>
                           <FileText size={16} />
                         </ActionIcon>
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 2b767d082..e58f5bfc8 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -389,6 +389,7 @@ export const URL_CONSTANTS = {
     MARK_READY_PICKUP: (id: string) => `/warehouse-inventory/${id}/ready-for-pickup`,
     RELEASE: (id: string) => `/warehouse-inventory/${id}/release`,
     RELEASE_DOCUMENT: (id: string) => `/warehouse-inventory/${id}/release-document`,
+    GRN_DOCUMENT: (id: string) => `/warehouse-inventory/${id}/grn-document`,
     HANDOVER_DOCUMENT: (id: string) => `/warehouse-inventory/${id}/handover-document`,
     DELIVER: (id: string) => `/warehouse-inventory/${id}/deliver`,
     // Receive (Import/Export bulk)
diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index 1217b8762..a60559d5d 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,6 +1,6 @@
-export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
 
-// export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportWarehouseFlowPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportWarehouseFlowPage.tsx
index bf086f1ce..f75d02304 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportWarehouseFlowPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportWarehouseFlowPage.tsx
@@ -1,5 +1,6 @@
-import { Button, Card } from '@mantine/core';
-import { PackageSearch } from 'lucide-react';
+import { useState } from 'react';
+import { Button, Card, Group, Modal, Stack } from '@mantine/core';
+import { PackageSearch, Truck } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 
 import { PageContainer, PageHeader } from '@/components/page';
@@ -7,6 +8,7 @@ import { WarehouseFlowWorkbench } from '@/components/warehouses';
 
 export default function ExportWarehouseFlowPage() {
   const navigate = useNavigate();
+  const [receiveOpen, setReceiveOpen] = useState(false);
 
   return (
     <PageContainer>
@@ -14,15 +16,41 @@ export default function ExportWarehouseFlowPage() {
         title="Export Operations"
         subtitle="Manage export receive, terminal inventory, loading readiness, loaded items, and dispatch flow."
         action={
-          <Button variant="light" leftSection={<PackageSearch size={16} />} onClick={() => navigate('/dashboard/import-warehouse')}>
-            Import Operations
-          </Button>
+          <Group gap="xs">
+            <Button
+              fw={700}
+              leftSection={<Truck size={16} />}
+              onClick={() => setReceiveOpen(true)}
+            >
+              Receive for Loading
+            </Button>
+            <Button variant="light" leftSection={<PackageSearch size={16} />} onClick={() => navigate('/dashboard/import-warehouse')}>
+              Import Operations
+            </Button>
+          </Group>
         }
       />
 
       <Card>
         <WarehouseFlowWorkbench direction="EXPORT" />
       </Card>
+
+      <Modal
+        opened={receiveOpen}
+        onClose={() => setReceiveOpen(false)}
+        title="Receive for loading"
+        centered
+        size="80rem"
+      >
+        <Stack gap="md">
+          <WarehouseFlowWorkbench enabled={receiveOpen} direction="EXPORT" />
+          <Group justify="flex-end">
+            <Button variant="default" onClick={() => setReceiveOpen(false)}>
+              Close
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 9946ffbb1..01569882a 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -656,11 +656,11 @@ export const api = {
       ({ filter }) => ["warehouse-inventory", "inquiry", filter],
     ),
 
-    eligibleBookings: endpoint<void, EligibleBooking[]>(
+    eligibleBookings: endpoint<{ direction?: 'IMPORT' | 'EXPORT' } | void, EligibleBooking[]>(
       "warehouse-inventory",
       "eligible-bookings",
-      () => warehouseService.eligibleBookings().then((r) => r.data),
-      () => ["warehouse-inventory", "eligible-bookings"],
+      (input) => warehouseService.eligibleBookings(input?.direction).then((r) => r.data),
+      (input) => ["warehouse-inventory", "eligible-bookings", input?.direction ?? "ALL"],
     ),
 
     readyToLoadExport: endpoint<void, ReadyToLoadRow[]>(
diff --git a/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts b/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
index 83909c415..5aca5bd3f 100644
--- a/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
@@ -137,6 +137,10 @@ export const warehouseService = {
     apiClient.get<Blob>(URL_CONSTANTS.WAREHOUSE_INVENTORY.RELEASE_DOCUMENT(id), {
       responseType: 'blob',
     }),
+  downloadGrnDocument: (id: string) =>
+    apiClient.get<Blob>(URL_CONSTANTS.WAREHOUSE_INVENTORY.GRN_DOCUMENT(id), {
+      responseType: 'blob',
+    }),
   downloadHandoverDocument: (id: string) =>
     apiClient.get<Blob>(URL_CONSTANTS.WAREHOUSE_INVENTORY.HANDOVER_DOCUMENT(id), {
       responseType: 'blob',
diff --git a/apps/edr-freight-web/backoffice/src/types/warehouse.ts b/apps/edr-freight-web/backoffice/src/types/warehouse.ts
index bca62a21c..e324f299a 100644
--- a/apps/edr-freight-web/backoffice/src/types/warehouse.ts
+++ b/apps/edr-freight-web/backoffice/src/types/warehouse.ts
@@ -190,6 +190,7 @@ export interface WarehouseInventoryItem {
   quantity: number;
   weight: number;
   volume: number | null;
+  grnNumber: string | null;
   status: InventoryStatus;
   inspectionStatus: string | null;
   arrivedAt: string | null;
@@ -203,6 +204,8 @@ export interface WarehouseInventoryItem {
   readyForPickupAt: string | null;
   releaseDate: string | null;
   releaseOrderReference: string | null;
+  handoverDocumentReference?: string | null;
+  handoverDocumentDate?: string | null;
   deliveredAt: string | null;
   notes: string | null;
   warehouse?: Warehouse | null;
@@ -472,6 +475,7 @@ export interface ReadyToLoadRow {
   containerNumber: string | null;
   cargoType: string | null;
   weight: number | null;
+  grnNumber: string | null;
   origin: string | null;
   destination: string | null;
   inspectionStatus: string | null;
@@ -564,6 +568,7 @@ export interface ImportUnloadedItem {
   containerNumber: string | null;
   cargoType: string | null;
   weight: number | null;
+  grnNumber: string | null;
   trainSchedule: string | null;
   inspectionStatus: string | null;
   pickupOption: string;
@@ -571,6 +576,8 @@ export interface ImportUnloadedItem {
   currentStatus: string;
   releaseDate: string | null;
   releaseOrderReference: string | null;
+  handoverDocumentReference: string | null;
+  handoverDocumentDate: string | null;
   deliveredAt: string | null;
 }
 
diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index 1b070d87d..b2d93ca3a 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,5 @@
-export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-// export const API_BASE_URL = 'http://localhost:3001';
+//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
index ab26c9365..b3acc1667 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
@@ -9,6 +9,7 @@ import {
   ContractSignButton,
   bookingIsSignable,
 } from "@/pages/bookings/contract/ContractSignButton";
+import { ApproveDeliveryButton } from "@/pages/bookings/delivery/ApproveDeliveryButton";
 
 interface BookingRowProps {
   booking: any;
@@ -35,6 +36,7 @@ export const BookingRow = memo(function BookingRow({
   // Contract ready for signature → "View & sign" jumps straight to the
   // full-page contract viewer where the signature flow lives.
   const canSign = bookingIsSignable(booking);
+  const canApproveDelivery = booking.status === "COMPLETED";
   const origin = booking.originYard?.label ?? booking.originYard?.code ?? "—";
   const dest =
     booking.destinationYard?.label ?? booking.destinationYard?.code ?? "—";
@@ -99,6 +101,12 @@ export const BookingRow = memo(function BookingRow({
             <PayNowButton booking={booking} size="sm" />
           ) : canSign ? (
             <ContractSignButton booking={booking} size="sm" />
+          ) : canApproveDelivery ? (
+            <ApproveDeliveryButton
+              bookingId={booking.id}
+              size="sm"
+              stopPropagation
+            />
           ) : hasInlineAction ? (
             <BookingActionButton booking={booking} size="sm" />
           ) : (
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
index c1a5ee0c9..065ee8385 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
@@ -11,6 +11,7 @@ import { useFileViewer } from "@/hooks/useFileViewer";
 import { paymentsService, type PaymentMethod } from "@/services/payments.service";
 import type { Freight } from "@edr/types";
 
+import { ApproveDeliveryButton } from "../delivery/ApproveDeliveryButton";
 import { ActivityCard } from "./components/ActivityCard";
 import { ClearanceCard } from "./components/ClearanceCard";
 import { ContainersCard } from "./components/ContainersCard";
@@ -72,6 +73,7 @@ export function ReadonlyBookingView({ booking }: { booking: Freight.IBooking })
     (isGeneralContract
       ? status === "FULLY_EXECUTED"
       : status === "SELECTED_FOR_BATCH");
+  const canApproveDelivery = status === "COMPLETED";
   const showCountdown = canPay && !!booking.paymentDeadline;
   const isExpired = status === "EXPIRED";
   const isPendingConsolidation = status === "PENDING_CONSOLIDATION";
@@ -93,14 +95,20 @@ export function ReadonlyBookingView({ booking }: { booking: Freight.IBooking })
       <PageHeader
         booking={booking}
         actions={
-          canPay &&
-          !showCountdown && (
-            <HeaderButton
-              green
-              icon={<CreditCard size={16} />}
-              label="Pay now"
-              onClick={() => setPayModalOpen(true)}
-            />
+          (canApproveDelivery || (canPay && !showCountdown)) && (
+            <Group gap={8} wrap="nowrap">
+              {canApproveDelivery && (
+                <ApproveDeliveryButton bookingId={booking.id} />
+              )}
+              {canPay && !showCountdown && (
+                <HeaderButton
+                  green
+                  icon={<CreditCard size={16} />}
+                  label="Pay now"
+                  onClick={() => setPayModalOpen(true)}
+                />
+              )}
+            </Group>
           )
         }
         menuActions={{
@@ -248,4 +256,4 @@ export function ReadonlyBookingView({ booking }: { booking: Freight.IBooking })
       {viewer}
     </PageShell>
   );
-}
\ No newline at end of file
+}
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/delivery/ApproveDeliveryButton.tsx b/apps/edr-freight-web/portal/src/pages/bookings/delivery/ApproveDeliveryButton.tsx
new file mode 100644
index 000000000..0f0ded4ef
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/delivery/ApproveDeliveryButton.tsx
@@ -0,0 +1,73 @@
+import { Button, type ButtonProps } from "@mantine/core";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { CheckCircle2 } from "lucide-react";
+import type { MouseEvent } from "react";
+import toast from "react-hot-toast";
+import { useNavigate } from "react-router-dom";
+
+import { api } from "@/services/api";
+
+type ApproveDeliveryButtonProps = ButtonProps & {
+  bookingId: string;
+  stopPropagation?: boolean;
+  onApproved?: () => void;
+};
+
+const errorMessage = (error: unknown) => {
+  const data = (error as { response?: { data?: { message?: string | string[] } } })
+    ?.response?.data;
+  if (Array.isArray(data?.message)) return data.message.join(", ");
+  if (data?.message) return data.message;
+  return error instanceof Error ? error.message : "Could not approve delivery";
+};
+
+export function ApproveDeliveryButton({
+  bookingId,
+  stopPropagation,
+  onApproved,
+  size = "sm",
+  variant = "filled",
+  ...props
+}: ApproveDeliveryButtonProps) {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    ...api.bookings.approveDelivery.mutationOptions(),
+    onSuccess: async () => {
+      toast.success("Delivery approved and handover signed");
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: api.bookings.get.queryKey({ id: bookingId }) }),
+        queryClient.invalidateQueries({ queryKey: api.bookings.list.queryKey() }),
+        queryClient.invalidateQueries({ queryKey: ["companies", "getDashboard"] }),
+      ]);
+      onApproved?.();
+    },
+    onError: (error) => {
+      const message = errorMessage(error);
+      toast.error(message);
+      if (message.toLowerCase().includes("save your signature")) {
+        navigate("/signature");
+      }
+    },
+  });
+
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    if (stopPropagation) event.stopPropagation();
+    mutation.mutate({ id: bookingId });
+  };
+
+  return (
+    <Button
+      {...props}
+      size={size}
+      variant={variant}
+      color="edr-green"
+      leftSection={<CheckCircle2 size={16} />}
+      loading={mutation.isPending}
+      onClick={handleClick}
+    >
+      Approve delivery
+    </Button>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/services/api.ts b/apps/edr-freight-web/portal/src/services/api.ts
index 4bb5e16e8..e1f9df4e5 100644
--- a/apps/edr-freight-web/portal/src/services/api.ts
+++ b/apps/edr-freight-web/portal/src/services/api.ts
@@ -8,6 +8,7 @@ import type {
 } from "@/types/fileUploadSettings";
 import {
   bookingsService,
+  type ApproveDeliveryResponse,
   BookingListFilter,
   CreateBookingPayload,
   GeneratePriceResponse,
@@ -297,6 +298,12 @@ export const api = {
       ({ orderId }) => bookingsService.checkPayment(orderId),
     ),
 
+    approveDelivery: endpoint<{ id: string }, ApproveDeliveryResponse>(
+      "bookings",
+      "approveDelivery",
+      ({ id }) => bookingsService.approveDelivery(id),
+    ),
+
     getBookableSchedules: endpoint<
       { originYardId?: string; destinationYardId?: string },
       Freight.BookableScheduleItem[]

From 468ac8b28a83c2681062293b24d9985184e29072 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 08:31:26 +0300
Subject: [PATCH 40/63] fix

---
 .../src/migrations/1821000000002-CreateInvoices.ts          | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 5c42cad65..6ed649d5a 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -27,7 +27,7 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
     `);
 
     await queryRunner.query(`
-      CREATE TABLE freight.invoices (
+      CREATE IF NOT EXISTS TABLE freight.invoices (
         id uuid NOT NULL DEFAULT uuid_generate_v4(),
         invoice_number varchar(64) NOT NULL,
         company_id uuid NOT NULL,
@@ -96,6 +96,8 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
   public async down(queryRunner: QueryRunner): Promise<void> {
     await queryRunner.query(`DROP TABLE IF EXISTS freight.invoice_lines;`);
     await queryRunner.query(`DROP TABLE IF EXISTS freight.invoices;`);
-    await queryRunner.query(`DROP TYPE IF EXISTS freight.invoices_status_enum;`);
+    await queryRunner.query(
+      `DROP TYPE IF EXISTS freight.invoices_status_enum;`,
+    );
   }
 }

From c299973bb0e7adaf61d6155121395173bbb773aa Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 08:38:27 +0300
Subject: [PATCH 41/63] fix

---
 .../src/migrations/1821000000002-CreateInvoices.ts              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
index 6ed649d5a..5fd7cd0ad 100644
--- a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -27,7 +27,7 @@ export class CreateInvoices1821000000002 implements MigrationInterface {
     `);
 
     await queryRunner.query(`
-      CREATE IF NOT EXISTS TABLE freight.invoices (
+      CREATE TABLE IF NOT EXISTS freight.invoices (
         id uuid NOT NULL DEFAULT uuid_generate_v4(),
         invoice_number varchar(64) NOT NULL,
         company_id uuid NOT NULL,

From 004c40059f3df994d8a5fe9a63a2e6dbc8334d88 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 09:13:48 +0300
Subject: [PATCH 42/63] fix: api url

---
 apps/edr-freight-web/backoffice/src/constants/apiConfig.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index a60559d5d..f4b707fbc 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,6 +1,6 @@
-//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+export const API_BASE_URL = "https://edrfreightapi.triaplc.com";
 
-export const API_BASE_URL = 'http://localhost:3001';
+// export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the

From 0f762172bf775ab1d2f15dad6caf6531835cba8a Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 09:19:32 +0300
Subject: [PATCH 43/63] fix: api url backoffice

---
 apps/edr-freight-web/portal/src/constants/apiConfig.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index b2d93ca3a..40c6c0041 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,5 @@
-//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = "https://edrfreightapi.triaplc.com";
+// export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
@@ -12,4 +12,3 @@ export function fileViewUrl(fileId: string, download = false): string {
   const base = `${API_BASE_URL}/api/files/${fileId}`;
   return download ? `${base}?download=1` : base;
 }
-

From 5e43820efa7bff1955a0d341be6371399895f990 Mon Sep 17 00:00:00 2001
From: SennayT <wsennay@gmail.com>
Date: Tue, 30 Jun 2026 10:38:53 +0300
Subject: [PATCH 44/63] revert changes to dockerfile

---
 apps/edr-passenger-api/Dockerfile | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/apps/edr-passenger-api/Dockerfile b/apps/edr-passenger-api/Dockerfile
index 4941ceb46..2b0ee8041 100644
--- a/apps/edr-passenger-api/Dockerfile
+++ b/apps/edr-passenger-api/Dockerfile
@@ -23,10 +23,10 @@ RUN pnpm turbo build --filter="@edr/passenger-api..."
 FROM base AS deployer
 COPY --from=builder /app/ .
 RUN pnpm deploy --filter="@edr/passenger-api" --legacy /deploy
-# Copy prisma directory and generate client in deploy location
-RUN cp -r apps/edr-passenger-api/prisma /deploy/ && \
-    cd /deploy && \
-    npx prisma generate --schema=prisma/schema.prisma
+RUN if [ -d node_modules/.prisma ]; then \
+      mkdir -p /deploy/node_modules && \
+      cp -r node_modules/.prisma /deploy/node_modules/.prisma; \
+    fi
 
 # --- Migration image: built in CI, run as a one-shot `docker run --rm --env-file ...`
 # against the real DB, as its own gated step *before* the app image is built/deployed.
@@ -37,10 +37,7 @@ WORKDIR /deploy
 RUN corepack enable && corepack prepare pnpm@11.1.1 --activate
 ENV CI=true
 ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
-# Copy the resolution script
-COPY apps/edr-passenger-api/scripts/resolve-migrations.sh /deploy/scripts/
-RUN chmod +x /deploy/scripts/resolve-migrations.sh
-CMD ["sh", "-c", "/deploy/scripts/resolve-migrations.sh && npm run prisma:generate && npm run prisma:migrate && npm run prisma:seed"]
+CMD ["sh", "-c", "npm run prisma:generate && npm run prisma:migrate && npm run prisma:seed"]
 
 FROM node:24.15.0-alpine AS runner
 RUN apk add --no-cache libc6-compat

From e7e523b3b2ff8ce73c299f242221e053a3a5a641 Mon Sep 17 00:00:00 2001
From: SennayT <wsennay@gmail.com>
Date: Tue, 30 Jun 2026 08:39:38 +0000
Subject: [PATCH 45/63] geerate prisma client after deploying

---
 apps/edr-passenger-api/Dockerfile | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/edr-passenger-api/Dockerfile b/apps/edr-passenger-api/Dockerfile
index 2b0ee8041..a8dfcddfd 100644
--- a/apps/edr-passenger-api/Dockerfile
+++ b/apps/edr-passenger-api/Dockerfile
@@ -23,10 +23,12 @@ RUN pnpm turbo build --filter="@edr/passenger-api..."
 FROM base AS deployer
 COPY --from=builder /app/ .
 RUN pnpm deploy --filter="@edr/passenger-api" --legacy /deploy
-RUN if [ -d node_modules/.prisma ]; then \
-      mkdir -p /deploy/node_modules && \
-      cp -r node_modules/.prisma /deploy/node_modules/.prisma; \
-    fi
+# The generated Prisma client is NOT in the pnpm store (it's an output of
+# `prisma generate`), so `pnpm deploy` does not copy it into /deploy. Regenerate
+# it here so the runtime enum values imported from @prisma/client (Currency, …)
+# are real objects instead of undefined — otherwise @IsEnum(Currency) throws
+# "Cannot convert undefined or null to object" at module load.
+RUN cd /deploy && npm run prisma:generate
 
 # --- Migration image: built in CI, run as a one-shot `docker run --rm --env-file ...`
 # against the real DB, as its own gated step *before* the app image is built/deployed.

From 3c5f5b586183f4cc1e1354353109f7c4dcf73468 Mon Sep 17 00:00:00 2001
From: SennayT <wsennay@gmail.com>
Date: Tue, 30 Jun 2026 09:54:07 +0000
Subject: [PATCH 46/63] fix: add docker cache for pnpm installations

---
 apps/edr-freight-api/Dockerfile               |  8 +++++++-
 apps/edr-passenger-api/Dockerfile             |  9 ++++++++-
 apps/edr-payment-api/Dockerfile               |  8 +++++++-
 checkpoint.md                                 | 20 +++++++++++++++++++
 .../docker/Dockerfile.passenger-web           |  7 ++++++-
 infrastructure/docker/Dockerfile.web          |  4 ++++
 6 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/apps/edr-freight-api/Dockerfile b/apps/edr-freight-api/Dockerfile
index b0850737b..f9107ed23 100644
--- a/apps/edr-freight-api/Dockerfile
+++ b/apps/edr-freight-api/Dockerfile
@@ -3,6 +3,10 @@
 
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
+# Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
+# `--mount=type=cache,target=/pnpm/store` cache actually persists deps across builds.
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 
@@ -14,6 +18,7 @@ FROM base AS installer
 COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
+    --mount=type=cache,id=pnpm,target=/pnpm/store \
     pnpm install --frozen-lockfile
 
 FROM base AS builder
@@ -23,7 +28,8 @@ RUN pnpm turbo build --filter="@edr/freight-api..."
 
 FROM base AS deployer
 COPY --from=builder /app/ .
-RUN pnpm deploy --filter="@edr/freight-api" --prod --legacy /deploy
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm deploy --filter="@edr/freight-api" --prod --legacy /deploy
 
 FROM node:24.15.0-alpine AS runner
 RUN apk add --no-cache libc6-compat
diff --git a/apps/edr-passenger-api/Dockerfile b/apps/edr-passenger-api/Dockerfile
index a8dfcddfd..45b365496 100644
--- a/apps/edr-passenger-api/Dockerfile
+++ b/apps/edr-passenger-api/Dockerfile
@@ -4,6 +4,12 @@
 # `migration` stage, invoked as a one-shot container in CI before deploy.
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
+# Put the pnpm content-addressable store under PNPM_HOME so the BuildKit
+# `--mount=type=cache,target=/pnpm/store` below actually persists it across
+# builds. Without this, pnpm stores in ~/.local/share/pnpm/store and the
+# cache mount is a no-op — deps re-download on every pipeline run.
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 FROM base AS pruner
@@ -22,7 +28,8 @@ RUN pnpm --filter "@edr/passenger-api" exec prisma generate
 RUN pnpm turbo build --filter="@edr/passenger-api..."
 FROM base AS deployer
 COPY --from=builder /app/ .
-RUN pnpm deploy --filter="@edr/passenger-api" --legacy /deploy
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm deploy --filter="@edr/passenger-api" --legacy /deploy
 # The generated Prisma client is NOT in the pnpm store (it's an output of
 # `prisma generate`), so `pnpm deploy` does not copy it into /deploy. Regenerate
 # it here so the runtime enum values imported from @prisma/client (Currency, …)
diff --git a/apps/edr-payment-api/Dockerfile b/apps/edr-payment-api/Dockerfile
index 5cddf5232..76d211a20 100644
--- a/apps/edr-payment-api/Dockerfile
+++ b/apps/edr-payment-api/Dockerfile
@@ -2,6 +2,10 @@
 # Build from monorepo root: docker build -f apps/edr-payment-api/Dockerfile .
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
+# Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
+# `--mount=type=cache,target=/pnpm/store` cache actually persists deps across builds.
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 FROM base AS pruner
@@ -11,6 +15,7 @@ FROM base AS installer
 COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
+    --mount=type=cache,id=pnpm,target=/pnpm/store \
     pnpm install --frozen-lockfile
 FROM base AS builder
 COPY --from=installer /app/ .
@@ -18,7 +23,8 @@ COPY --from=pruner /app/out/full/ .
 RUN pnpm turbo build --filter="@edr/payment-api..."
 FROM base AS deployer
 COPY --from=builder /app/ .
-RUN pnpm deploy --filter="@edr/payment-api" --prod --legacy --ignore-scripts /deploy
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm deploy --filter="@edr/payment-api" --prod --legacy --ignore-scripts /deploy
 
 # --- Migration image: built in CI, run as a one-shot `docker run --rm --env-file ...`
 # against the real DB, as its own gated step *before* the app image is built/deployed.
diff --git a/checkpoint.md b/checkpoint.md
index d9665e1fc..4f357ab6c 100644
--- a/checkpoint.md
+++ b/checkpoint.md
@@ -75,6 +75,10 @@
 - `apps/edr-passenger-api/docker-entrypoint.sh`
 - `apps/edr-passenger-api/prisma/seed.ts`
 - `infrastructure/docker/Dockerfile.passenger-web` (NEW)
+- `apps/edr-freight-api/Dockerfile` (MODIFIED — pnpm store cache)
+- `apps/edr-passenger-api/Dockerfile` (MODIFIED — prisma generate in /deploy + pnpm store cache)
+- `apps/edr-payment-api/Dockerfile` (MODIFIED — pnpm store cache)
+- `infrastructure/docker/Dockerfile.web` (MODIFIED — pnpm store cache)
 - `apps/edr-passenger-web/portal/next.config.js` (MODIFIED)
 - `apps/edr-passenger-web/backoffice/next.config.js` (MODIFIED)
 - `DEPLOYMENT.md` (MODIFIED)
@@ -85,6 +89,22 @@
     - `live/page.tsx` — replaced stub with real LiveTrackingPage using `liveApi` (trips, crowd signals, delay/status stats)
     - `notifications/page.tsx` — replaced hardcoded mock + broken `Table` import with real page using `notificationsApi` (templates list, send form, notification history tab)
 
+## Prisma Client Missing After `pnpm deploy` (Latest)
+
+20. Fixed passenger API crash in Docker (`TypeError: Cannot convert undefined or null to object` at `class-validator` `IsEnum`, triggered by `dist/modules/fare-engine/currency.dto.js`):
+    - Root cause: `currency.dto.ts` imports the `Currency` enum (a runtime value) from `@prisma/client`. The generated Prisma client is an output of `prisma generate`, not a package in the pnpm store, so `pnpm deploy` did not copy it into `/deploy`. At runtime `Currency` resolved to `undefined` → `@IsEnum(undefined)` → `Object.entries(undefined)` throws at module load.
+    - Prisma 6 + pnpm writes the client to `node_modules/.pnpm/@prisma+client@.../node_modules/.prisma/client`, **not** root `node_modules/.prisma`. The old `cp` rescue in the Dockerfile guarded on `[ -d node_modules/.prisma ]` (root) which never existed → silently skipped.
+    - Fix in `apps/edr-passenger-api/Dockerfile`: replaced the broken `cp` with `RUN cd /deploy && npm run prisma:generate` after `pnpm deploy`, regenerating the client into the exact runtime-resolve path (`/deploy/node_modules/.prisma/client`). Safe because deploy has no `--prod` flag (so the `prisma` CLI ships) and `package.json` declares the schema path.
+    - Affected 16 passenger-api files importing from `@prisma/client`; `currency.dto.js` just loaded first. payment-api unaffected (TypeORM, no Prisma).
+
+## pnpm Store Build Cache Fix (Latest)
+
+21. Fixed Docker builds re-downloading all dependencies every pipeline run:
+    - Root cause: install steps used `--mount=type=cache,id=pnpm,target=/pnpm/store`, but nothing set pnpm's store-dir to `/pnpm/store`. Default store (`~/.local/share/pnpm/store`) was never under the mount → BuildKit cached an empty dir → full re-download each build. The two web Dockerfiles had the mount but it was dead; the two API Dockerfiles (freight, payment) had no mount at all.
+    - Fix: added `ENV PNPM_HOME="/pnpm"` (+ PATH) to the `base` stage of all 5 Dockerfiles so the store resolves to `/pnpm/store`, matching the mount. Added the cache mount to every `pnpm install` and `pnpm deploy` step that lacked it.
+    - Files: `apps/edr-freight-api/Dockerfile`, `apps/edr-passenger-api/Dockerfile`, `apps/edr-payment-api/Dockerfile`, `infrastructure/docker/Dockerfile.web`, `infrastructure/docker/Dockerfile.passenger-web`.
+    - Caveat: BuildKit cache mounts live on the runner host; persists only while the same self-hosted runner/builder is reused and not pruned (`docker builder prune` wipes it).
+
 ## Next Actions
 
 1. Run full CI on all target branches (`main`, `dev`, `staging`) and verify matrix job behavior.
diff --git a/infrastructure/docker/Dockerfile.passenger-web b/infrastructure/docker/Dockerfile.passenger-web
index 735a19e8e..9d9adac08 100644
--- a/infrastructure/docker/Dockerfile.passenger-web
+++ b/infrastructure/docker/Dockerfile.passenger-web
@@ -18,6 +18,10 @@ ARG NEXT_PUBLIC_API_URL
 
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
+# Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
+# `--mount=type=cache,target=/pnpm/store` cache actually persists deps across builds.
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 
@@ -45,7 +49,8 @@ RUN pnpm turbo build --filter="${APP_PACKAGE}..."
 FROM base AS deployer
 ARG APP_PACKAGE
 COPY --from=builder /app/ .
-RUN pnpm deploy --filter="${APP_PACKAGE}" --prod --legacy /deploy
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm deploy --filter="${APP_PACKAGE}" --prod --legacy /deploy
 
 FROM node:24.15.0-alpine AS runner
 ARG APP_PATH
diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index 1ccdeb81f..22ec91563 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -9,6 +9,10 @@ ARG NEXT_PUBLIC_API_URL=http://localhost:4000
 
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
+# Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
+# `--mount=type=cache,target=/pnpm/store` cache actually persists deps across builds.
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 

From fdb77a703652c50d56905a3b0bfe7c701f94ff24 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 13:49:52 +0300
Subject: [PATCH 47/63] fix: testing the env

---
 apps/edr-freight-web/portal/src/constants/apiConfig.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index 40c6c0041..59e5297df 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,4 +1,4 @@
-export const API_BASE_URL = "https://edrfreightapi.triaplc.com";
+export const API_BASE_URL = import.meta.env.VITE_BASE_API_URL;
 // export const API_BASE_URL = 'http://localhost:3001';
 
 /**

From 21cf24950de5ed7af87032b12c28835254a361ac Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 10:50:43 +0000
Subject: [PATCH 48/63] feat: add partial payment to match the warehouse
 invoice before migration

---
 ...0000000-ExtendInvoicesForPartialPayment.ts |  71 ++++++++++
 .../modules/billing/billing.service.spec.ts   |  82 ++++++++++++
 .../src/modules/billing/billing.service.ts    | 124 +++++++++++++++++-
 .../billing/entities/invoice.entity.ts        |  33 +++++
 packages/types/src/freight/index.ts           |   4 +
 5 files changed, 309 insertions(+), 5 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts

diff --git a/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts b/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts
new file mode 100644
index 000000000..55239c13f
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts
@@ -0,0 +1,71 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Extend `freight.invoices` into the billing record of record for every source
+ * (booking, demurrage, warehouse fees, …) so warehouse fee invoices can be
+ * centralized onto it instead of the parallel `warehouse_fee_invoices` table.
+ *
+ * Adds money tracking that supports partial payment (`subtotal/tax/paid/balance`),
+ * a `paid_at` stamp, a `payments` jsonb ledger, and the `ISSUED` / `PARTIALLY_PAID`
+ * statuses the warehouse flow uses.
+ *
+ * Matches billing/entities/invoice.entity.ts. All columns are additive with
+ * defaults, so existing booking/demurrage rows are unaffected.
+ */
+export class ExtendInvoicesForPartialPayment1828000000000
+  implements MigrationInterface
+{
+  name = "ExtendInvoicesForPartialPayment1828000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // New statuses. ADD VALUE is non-transactional-value-safe on PG 12+ as long
+    // as the value is not referenced in the same transaction (it is not here).
+    await queryRunner.query(
+      `ALTER TYPE freight.invoices_status_enum ADD VALUE IF NOT EXISTS 'ISSUED' BEFORE 'PENDING';`,
+    );
+    await queryRunner.query(
+      `ALTER TYPE freight.invoices_status_enum ADD VALUE IF NOT EXISTS 'PARTIALLY_PAID' BEFORE 'PAID';`,
+    );
+
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        ADD COLUMN IF NOT EXISTS subtotal_amount numeric(14, 2) NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS tax_amount numeric(14, 2) NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS paid_amount numeric(14, 2) NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS balance_amount numeric(14, 2) NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS paid_at timestamptz,
+        ADD COLUMN IF NOT EXISTS payments jsonb NOT NULL DEFAULT '[]';
+    `);
+
+    // Backfill existing rows: subtotal mirrors the total (no tax was modeled),
+    // the outstanding balance is the full total for unpaid invoices.
+    await queryRunner.query(`
+      UPDATE freight.invoices
+         SET subtotal_amount = total_amount,
+             balance_amount  = total_amount;
+    `);
+
+    // Already-settled invoices: fully paid, zero balance, stamped from updated_at.
+    await queryRunner.query(`
+      UPDATE freight.invoices
+         SET paid_amount    = total_amount,
+             balance_amount = 0,
+             paid_at        = updated_at
+       WHERE status = 'PAID';
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        DROP COLUMN IF EXISTS payments,
+        DROP COLUMN IF EXISTS paid_at,
+        DROP COLUMN IF EXISTS balance_amount,
+        DROP COLUMN IF EXISTS paid_amount,
+        DROP COLUMN IF EXISTS tax_amount,
+        DROP COLUMN IF EXISTS subtotal_amount;
+    `);
+    // Postgres cannot drop individual enum values; ISSUED / PARTIALLY_PAID are
+    // left on freight.invoices_status_enum (harmless, unused after down).
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 0e6d97de0..5d407d3cd 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -180,6 +180,88 @@ describe("BillingService.markInvoiceAsPaid", () => {
   });
 });
 
+describe("BillingService.recordPayment", () => {
+  function serviceFor(invoice: Record<string, unknown> | null) {
+    const mg = {
+      findOne: jest.fn().mockResolvedValue(invoice),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const events = makeEvents();
+    const service = new BillingService(
+      { manager: mg } as never,
+      {} as never,
+      {} as never,
+      events as never,
+      {} as never, // payment
+      {} as never, // companies
+    );
+    return { service, mg, events };
+  }
+
+  const openInvoice = (overrides: Record<string, unknown> = {}) => ({
+    id: "inv-1",
+    status: Freight.InvoiceStatus.Issued,
+    source: "warehouse",
+    sourceId: "inv-item-1",
+    totalAmount: 1000,
+    paidAmount: 0,
+    balanceAmount: 1000,
+    payments: [],
+    paidAt: null,
+    ...overrides,
+  });
+
+  it("moves to PARTIALLY_PAID and emits no event on a partial payment", async () => {
+    const { service, mg, events } = serviceFor(openInvoice());
+
+    const updated = await service.recordPayment("inv-1", { amount: 400, method: "CASH" });
+
+    expect(updated.status).toBe(Freight.InvoiceStatus.PartiallyPaid);
+    expect(updated.paidAmount).toBe(400);
+    expect(updated.balanceAmount).toBe(600);
+    expect(updated.payments).toHaveLength(1);
+    expect(mg.update).toHaveBeenCalledWith(
+      expect.anything(),
+      { id: "inv-1" },
+      expect.objectContaining({
+        status: Freight.InvoiceStatus.PartiallyPaid,
+        paidAmount: 400,
+        balanceAmount: 600,
+      }),
+    );
+    expect(events.emit).not.toHaveBeenCalled();
+  });
+
+  it("settles to PAID, stamps paidAt, and emits ${source}.invoice.paid when the balance clears", async () => {
+    const { service, mg, events } = serviceFor(openInvoice({ paidAmount: 400, balanceAmount: 600 }));
+
+    const updated = await service.recordPayment("inv-1", { amount: 600 });
+
+    expect(updated.status).toBe(Freight.InvoiceStatus.Paid);
+    expect(updated.balanceAmount).toBe(0);
+    expect(updated.paidAt).toBeInstanceOf(Date);
+    expect(mg.update).toHaveBeenCalled();
+    expect(events.emit).toHaveBeenCalledWith(
+      "warehouse.invoice.paid",
+      expect.objectContaining({ invoiceId: "inv-1", status: Freight.InvoiceStatus.Paid }),
+    );
+  });
+
+  it("rejects a non-positive amount", async () => {
+    const { service, mg } = serviceFor(openInvoice());
+    await expect(service.recordPayment("inv-1", { amount: 0 })).rejects.toThrow();
+    expect(mg.update).not.toHaveBeenCalled();
+  });
+
+  it("rejects payment against a cancelled invoice", async () => {
+    const { service, mg } = serviceFor(
+      openInvoice({ status: Freight.InvoiceStatus.Cancelled }),
+    );
+    await expect(service.recordPayment("inv-1", { amount: 100 })).rejects.toThrow();
+    expect(mg.update).not.toHaveBeenCalled();
+  });
+});
+
 describe("BillingService.settlePayable", () => {
   it("settles the source's open invoice PAID and emits ${source}.invoice.paid", async () => {
     const open = {
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 01b057a76..ce4341486 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,9 +1,16 @@
-import { forwardRef, Inject, Injectable, Logger, NotFoundException } from "@nestjs/common";
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
 import { Freight, PaymentReferenceType } from "@edr/types";
 import { DataSource, EntityManager, In } from "typeorm";
 
-import { Invoice } from "./entities/invoice.entity";
+import { Invoice, InvoicePayment } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
@@ -20,16 +27,32 @@ export interface PayInvoiceOptions {
   failureUrl?: string;
 }
 
+/** A single manual/offline settlement to record against an invoice. */
+export interface RecordPaymentInput {
+  /** Amount settled by this payment; must be > 0. */
+  amount: number;
+  method?: string | null;
+  reference?: string | null;
+  /** When the settlement occurred; defaults to now. */
+  paidAt?: Date;
+  metadata?: Record<string, unknown> | null;
+}
+
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
 const DEFAULT_DUE_DAYS = 14;
 
 /** Statuses an invoice can still be settled (paid/refunded/cancelled) from. */
 const OPEN_STATUSES: Freight.InvoiceStatus[] = [
   Freight.InvoiceStatus.Draft,
+  Freight.InvoiceStatus.Issued,
   Freight.InvoiceStatus.Pending,
+  Freight.InvoiceStatus.PartiallyPaid,
   Freight.InvoiceStatus.Overdue,
 ];
 
+/** Round to 2 decimals, avoiding binary float drift. */
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
 /** A single line to bill on a generated invoice. */
 export interface InvoiceLineInput {
   chargeType: string;
@@ -56,7 +79,11 @@ export interface GenerateInvoiceInput {
   companyProfileId: string;
   lines: InvoiceLineInput[];
   currency?: string;
-  /** Explicit total; defaults to the sum of line amounts. */
+  /** Explicit pre-tax subtotal; defaults to the sum of line amounts. */
+  subtotalAmount?: number;
+  /** Tax applied on top of the subtotal; defaults to 0. */
+  taxAmount?: number;
+  /** Explicit total; defaults to `subtotalAmount + taxAmount`. */
   totalAmount?: number;
   /** Issue date window; defaults to `DEFAULT_DUE_DAYS` from now. */
   dueAt?: Date;
@@ -230,8 +257,12 @@ export class BillingService {
       };
     });
 
+    const subtotalAmount =
+      input.subtotalAmount ??
+      lines.reduce((sum, l) => sum + Number(l.amount), 0);
+    const taxAmount = input.taxAmount ?? 0;
     const totalAmount =
-      input.totalAmount ?? lines.reduce((sum, l) => sum + Number(l.amount), 0);
+      input.totalAmount ?? round2(subtotalAmount + taxAmount);
 
     const dueAt =
       input.dueAt ??
@@ -250,7 +281,12 @@ export class BillingService {
         type: input.type,
         companyId: input.companyId,
         companyProfileId: input.companyProfileId,
-        totalAmount,
+        subtotalAmount: round2(subtotalAmount),
+        taxAmount: round2(taxAmount),
+        totalAmount: round2(totalAmount),
+        paidAmount: 0,
+        balanceAmount: round2(totalAmount),
+        payments: [],
         currency,
         status,
         issuedAt: issued ? new Date() : null,
@@ -293,6 +329,84 @@ export class BillingService {
     );
   }
 
+  /**
+   * Record a (possibly partial) settlement against an invoice and sync its
+   * status. Appends to the `payments` ledger, recomputes `paidAmount` /
+   * `balanceAmount`, and moves the invoice to PARTIALLY_PAID or — once the
+   * balance reaches zero — PAID, stamping `paidAt` and emitting
+   * `${source}.invoice.paid`. Use this for manual/offline settlement (e.g. cash
+   * at the warehouse counter); gateway settlement goes through
+   * {@link markInvoiceAsPaid}.
+   *
+   * Throws when the invoice is missing, cancelled, refunded, already fully paid,
+   * or when `amount` is not positive. Pass `manager` to enlist in a caller's
+   * transaction.
+   */
+  async recordPayment(
+    invoiceId: string,
+    input: RecordPaymentInput,
+    manager?: EntityManager,
+  ): Promise<Invoice> {
+    if (!(input.amount > 0)) {
+      throw new BadRequestException("Payment amount must be greater than zero.");
+    }
+
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    if (invoice.status === Freight.InvoiceStatus.Cancelled) {
+      throw new BadRequestException("Cannot pay a cancelled invoice.");
+    }
+    if (invoice.status === Freight.InvoiceStatus.Refunded) {
+      throw new BadRequestException("Cannot pay a refunded invoice.");
+    }
+    if (invoice.status === Freight.InvoiceStatus.Paid) {
+      throw new BadRequestException("Invoice is already fully paid.");
+    }
+
+    const at = input.paidAt ?? new Date();
+    const total = Number(invoice.totalAmount);
+    const paidAmount = round2(Number(invoice.paidAmount) + input.amount);
+    const balanceAmount = Math.max(0, round2(total - paidAmount));
+    const fullyPaid = paidAmount >= total;
+    const status = fullyPaid
+      ? Freight.InvoiceStatus.Paid
+      : Freight.InvoiceStatus.PartiallyPaid;
+
+    const entry: InvoicePayment = {
+      amount: round2(input.amount),
+      method: input.method ?? null,
+      reference: input.reference ?? null,
+      paidAt: at.toISOString(),
+      metadata: input.metadata ?? null,
+    };
+    const payments = [...(invoice.payments ?? []), entry];
+
+    await mg.update(
+      Invoice,
+      { id: invoice.id },
+      {
+        paidAmount,
+        balanceAmount,
+        status,
+        payments,
+        paidAt: fullyPaid ? at : invoice.paidAt ?? null,
+      } as never,
+    );
+
+    const updated = {
+      ...invoice,
+      paidAmount,
+      balanceAmount,
+      status,
+      payments,
+      paidAt: fullyPaid ? at : invoice.paidAt ?? null,
+    } as Invoice;
+
+    if (fullyPaid) this.emitInvoiceEvent("paid", updated);
+    return updated;
+  }
+
   /**
    * Mark an invoice refunded and emit `${source}.invoice.refunded`.
    * No-op when already refunded.
diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
index 61bc9c16b..23c332f80 100644
--- a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
@@ -5,6 +5,16 @@ import { PaymentEntity } from "../../payment/entities/payment.entity";
 import { Company } from "../../companies/entities/company.entity";
 import { CompanyProfile } from "../../companies/entities/company-profile.entity";
 
+/** A single recorded settlement against an invoice (payment ledger entry). */
+export interface InvoicePayment {
+  amount: number;
+  method?: string | null;
+  reference?: string | null;
+  /** ISO timestamp of when the settlement was recorded. */
+  paidAt: string;
+  metadata?: Record<string, unknown> | null;
+}
+
 @Entity({ schema: "freight", name: "invoices" })
 @Index(["companyId"])
 @Index(["companyProfileId"])
@@ -28,9 +38,24 @@ export class Invoice extends BaseEntity {
   @JoinColumn({ name: "company_profile_id" })
   companyProfile?: CompanyProfile;
 
+  /** Sum of line amounts before tax; defaults to `totalAmount` for tax-free invoices. */
+  @Column({ name: "subtotal_amount", type: "numeric", precision: 14, scale: 2, default: 0 })
+  subtotalAmount!: number;
+
+  @Column({ name: "tax_amount", type: "numeric", precision: 14, scale: 2, default: 0 })
+  taxAmount!: number;
+
   @Column({ name: "total_amount", type: "numeric", precision: 14, scale: 2 })
   totalAmount!: number;
 
+  /** Cumulative amount settled so far (supports partial payment). */
+  @Column({ name: "paid_amount", type: "numeric", precision: 14, scale: 2, default: 0 })
+  paidAmount!: number;
+
+  /** Outstanding balance = `totalAmount - paidAmount` (0 once fully paid). */
+  @Column({ name: "balance_amount", type: "numeric", precision: 14, scale: 2, default: 0 })
+  balanceAmount!: number;
+
   @Column({ name: "currency", type: "varchar", length: 8, default: "ETB" })
   currency!: string;
 
@@ -62,6 +87,14 @@ export class Invoice extends BaseEntity {
   @Column({ name: "issued_at", type: "timestamptz", nullable: true })
   issuedAt?: Date | null;
 
+  /** Set when the invoice is fully settled. */
+  @Column({ name: "paid_at", type: "timestamptz", nullable: true })
+  paidAt?: Date | null;
+
+  /** Ledger of individual settlements (manual or gateway), newest last. */
+  @Column({ name: "payments", type: "jsonb", default: () => "'[]'" })
+  payments!: InvoicePayment[];
+
   /** The ID of the payment that generated this invoice. */
   @Column({ name: "payment_id", type: "uuid", nullable: true })
   paymentId?: string | null;
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index dbfcf655d..171a294fb 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -131,7 +131,11 @@ export enum PaymentStatus {
 
 export enum InvoiceStatus {
   Draft = "DRAFT",
+  /** Issued and awaiting payment (alias of PENDING for fee invoices). */
+  Issued = "ISSUED",
   Pending = "PENDING",
+  /** Some, but not all, of the balance has been settled. */
+  PartiallyPaid = "PARTIALLY_PAID",
   Paid = "PAID",
   Overdue = "OVERDUE",
   Cancelled = "CANCELLED",

From 9619fbd9b0d7c580c6b4953ed306f705103cab84 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 13:58:57 +0300
Subject: [PATCH 49/63] fix: the hardcoded api url

---
 apps/edr-freight-web/portal/src/constants/apiConfig.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index 59e5297df..a285a8fd2 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,4 @@
 export const API_BASE_URL = import.meta.env.VITE_BASE_API_URL;
-// export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the

From 48340f5e0a25ca66a1cd32702766a4d14e665f4e Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 30 Jun 2026 14:05:28 +0300
Subject: [PATCH 50/63] fix: the hardcoded api url

---
 apps/edr-freight-web/backoffice/src/constants/apiConfig.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index f4b707fbc..842276815 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,4 +1,4 @@
-export const API_BASE_URL = "https://edrfreightapi.triaplc.com";
+export const API_BASE_URL = import.meta.env.VITE_BASE_API_URL;
 
 // export const API_BASE_URL = 'http://localhost:3001';
 

From 3eb4a24199cceef5c4a4e68027fbbb2b56a5518f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 11:29:28 +0000
Subject: [PATCH 51/63] fix: terminal clearing int vite

---
 apps/edr-freight-web/backoffice/package.json | 2 +-
 apps/edr-freight-web/portal/package.json     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/package.json b/apps/edr-freight-web/backoffice/package.json
index 93caae0a4..48b9bc0a9 100644
--- a/apps/edr-freight-web/backoffice/package.json
+++ b/apps/edr-freight-web/backoffice/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite --port 5183",
+    "dev": "vite --port 5183 --clearScreen false",
     "prebuild": "node -e \"const fs=require('fs'); fs.rmSync('dist',{recursive:true,force:true});\"",
     "build": "vite build",
     "preview": "vite preview --port 5183",
diff --git a/apps/edr-freight-web/portal/package.json b/apps/edr-freight-web/portal/package.json
index 9f866d756..960531fda 100644
--- a/apps/edr-freight-web/portal/package.json
+++ b/apps/edr-freight-web/portal/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite --port 5173",
+    "dev": "vite --port 5173 --clearScreen false",
     "build": "tsc -b && vite build",
     "preview": "vite preview --port 5173",
     "lint": "eslint src",

From 7fa18b8ee726ea41420afad945c73e48ba15a87a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 11:54:43 +0000
Subject: [PATCH 52/63] fix: reference type in payment service

---
 .../src/modules/payment/payment.service.ts    | 988 ++++++++++--------
 1 file changed, 527 insertions(+), 461 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 347fedc1e..738a6d118 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -1,11 +1,11 @@
 import {
-    BadRequestException,
-    forwardRef,
-    Inject,
-    Injectable,
-    InternalServerErrorException,
-    Logger,
-    NotFoundException,
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  Logger,
+  NotFoundException,
 } from "@nestjs/common";
 import { DataSource } from "typeorm";
 import { PaymentEntity } from "./entities/payment.entity";
@@ -18,73 +18,70 @@ import * as path from "path";
 import * as Handlebars from "handlebars";
 import { Booking } from "../bookings/entities/booking.entity";
 
+import { ClientAction, ProviderPaymentStatus } from "@edr/payment-providers";
 import {
-    ClientAction,
-    ProviderPaymentStatus,
-} from "@edr/payment-providers";
-import {
-    PaymentService as PaymentServiceEnum,
-    PaymentReferenceType,
-    PaymentIntentSnapshot,
-    ProviderMethod,
+  PaymentService as PaymentServiceEnum,
+  PaymentReferenceType,
+  PaymentIntentSnapshot,
+  ProviderMethod,
 } from "@edr/types";
 import {
-    InitiateResponseDto,
-    IntentStatusDto,
-    PaymentPlatformDto,
-    RefundDto,
+  InitiateResponseDto,
+  IntentStatusDto,
+  PaymentPlatformDto,
+  RefundDto,
 } from "./payments.dto";
 
 /** Everything the gateway needs to open an intent. Amount/currency are supplied by
  *  the caller (billing) — this service never derives them from a domain record. */
 export interface InitiateIntentInput {
-    /** Opaque domain reference (booking id, …). */
-    referenceId: string;
-    /** Invoice source that owns the intent ('booking', …) — stored on the projection. */
-    source: string;
-    /** Gateway reference type the intent is opened with (caller's domain decides it). */
-    referenceType: PaymentReferenceType;
-    /** Human-readable order ref shown on provider pages. */
-    orderRef: string;
-    /** Authoritative amount in minor units, computed by the caller. */
-    amountMinor: number;
-    currency: string;
-    /** Stored on the intent projection for receipts/dashboards. */
-    reason?: string;
-    /** Provider/method selector. */
-    method: ProviderMethod | string;
-    platform?: PaymentPlatformDto;
-    payerAccount?: string;
-    returnUrl?: string;
-    failureUrl?: string;
+  /** Opaque domain reference (booking id, …). */
+  referenceId: string;
+  /** Invoice source that owns the intent ('booking', …) — stored on the projection. */
+  source: string;
+  /** Gateway reference type the intent is opened with (caller's domain decides it). */
+  referenceType: PaymentReferenceType;
+  /** Human-readable order ref shown on provider pages. */
+  orderRef: string;
+  /** Authoritative amount in minor units, computed by the caller. */
+  amountMinor: number;
+  currency: string;
+  /** Stored on the intent projection for receipts/dashboards. */
+  reason?: string;
+  /** Provider/method selector. */
+  method: ProviderMethod | string;
+  platform?: PaymentPlatformDto;
+  payerAccount?: string;
+  returnUrl?: string;
+  failureUrl?: string;
 }
 
 export interface InitiateIntentResult {
-    intentId: string;
-    response: InitiateResponseDto;
-    /** True when the provider settled the charge synchronously during initiate. */
-    immediateSuccess: boolean;
-    providerTxnId?: string;
-    paidAt?: Date;
+  intentId: string;
+  response: InitiateResponseDto;
+  /** True when the provider settled the charge synchronously during initiate. */
+  immediateSuccess: boolean;
+  providerTxnId?: string;
+  paidAt?: Date;
 }
 
 const STATUS_MAP: Record<string, ProviderPaymentStatus> = {
-    "action-required": ProviderPaymentStatus.REQUIRES_ACTION,
-    "processing": ProviderPaymentStatus.PROCESSING,
-    "success": ProviderPaymentStatus.SUCCEEDED,
-    "failed": ProviderPaymentStatus.FAILED,
-    "canceled": ProviderPaymentStatus.CANCELLED,
-    "refunded": ProviderPaymentStatus.CANCELLED,
+  "action-required": ProviderPaymentStatus.REQUIRES_ACTION,
+  processing: ProviderPaymentStatus.PROCESSING,
+  success: ProviderPaymentStatus.SUCCEEDED,
+  failed: ProviderPaymentStatus.FAILED,
+  canceled: ProviderPaymentStatus.CANCELLED,
+  refunded: ProviderPaymentStatus.CANCELLED,
 };
 
 const PROVIDER_TO_METHOD: Record<string, PaymentEntity["method"]> = {
-    TELEBIRR: "telebirr",
-    CBE_BIRR: "cbe-birr",
-    EBIRR: "ebirr",
-    WAAFI: "waafi",
-    CARD: "card",
-    DMONEY: "dmoney",
-    CAC_BANK: "cac-bank",
+  TELEBIRR: "telebirr",
+  CBE_BIRR: "cbe-birr",
+  EBIRR: "ebirr",
+  WAAFI: "waafi",
+  CARD: "card",
+  DMONEY: "dmoney",
+  CAC_BANK: "cac-bank",
 };
 
 /**
@@ -96,426 +93,495 @@ const PROVIDER_TO_METHOD: Record<string, PaymentEntity["method"]> = {
  */
 @Injectable()
 export class PaymentService {
-    private readonly logger = new Logger(PaymentService.name);
+  private readonly logger = new Logger(PaymentService.name);
 
-    constructor(
-        private readonly datasource: DataSource,
-        private readonly paymentRepo: PaymentRepository,
-        private readonly paymentClient: PaymentClientService,
-        @Inject(forwardRef(() => BillingService))
-        private readonly billing: BillingService,
-    ) { }
+  constructor(
+    private readonly datasource: DataSource,
+    private readonly paymentRepo: PaymentRepository,
+    private readonly paymentClient: PaymentClientService,
+    @Inject(forwardRef(() => BillingService))
+    private readonly billing: BillingService,
+  ) { }
 
-    async getAll(filters: {
-        search?: string;
-        status?: string;
-        method?: string;
-        page?: number;
-        pageSize?: number;
-    }) {
-        const { search, status, method, page = 1, pageSize = 10 } = filters;
-        const skip = (page - 1) * pageSize;
+  async getAll(filters: {
+    search?: string;
+    status?: string;
+    method?: string;
+    page?: number;
+    pageSize?: number;
+  }) {
+    const { search, status, method, page = 1, pageSize = 10 } = filters;
+    const skip = (page - 1) * pageSize;
 
-        const qb = this.paymentRepo.createQueryBuilder("payment");
+    const qb = this.paymentRepo.createQueryBuilder("payment");
 
-        if (search) {
-            qb.andWhere(
-                "(payment.merchantOrderId ILIKE :search OR payment.refId ILIKE :search OR payment.transactionId ILIKE :search)",
-                { search: `%${search}%` },
-            );
-        }
-        if (status) {
-            qb.andWhere("payment.status = :status", { status });
-        }
-        if (method) {
-            qb.andWhere("payment.method = :method", { method });
-        }
+    if (search) {
+      qb.andWhere(
+        "(payment.merchantOrderId ILIKE :search OR payment.refId ILIKE :search OR payment.transactionId ILIKE :search)",
+        { search: `%${search}%` },
+      );
+    }
+    if (status) {
+      qb.andWhere("payment.status = :status", { status });
+    }
+    if (method) {
+      qb.andWhere("payment.method = :method", { method });
+    }
 
-        const [items, total] = await qb
-            .orderBy("payment.createdAt", "DESC")
-            .skip(skip)
-            .take(pageSize)
-            .getManyAndCount();
+    const [items, total] = await qb
+      .orderBy("payment.createdAt", "DESC")
+      .skip(skip)
+      .take(pageSize)
+      .getManyAndCount();
 
+    return {
+      items: items.map((p) => ({
+        id: p.id,
+        bookingId: p.refId,
+        amount: p.amount,
+        currency: p.currency,
+        method: p.method,
+        status: p.status,
+        merchantOrderId: p.merchantOrderId,
+        paidAt: p.paidAt,
+        createdAt: p.createdAt,
+      })),
+      total,
+      page,
+      pageSize,
+    };
+  }
+
+  /** Aggregate counts across ALL payments for the dashboard summary cards. */
+  async getSummary() {
+    const rows = await this.paymentRepo
+      .createQueryBuilder("payment")
+      .select("payment.status", "status")
+      .addSelect("COUNT(*)::int", "count")
+      .groupBy("payment.status")
+      .getRawMany<{ status: string; count: number }>();
+
+    const byStatus: Record<string, number> = {};
+    let total = 0;
+    for (const row of rows) {
+      byStatus[row.status] = row.count;
+      total += row.count;
+    }
+
+    const paidAgg = await this.paymentRepo
+      .createQueryBuilder("payment")
+      .select("COALESCE(SUM(payment.amount), 0)", "sum")
+      .where("payment.status = :status", { status: "success" })
+      .getRawOne<{ sum: string }>();
+
+    return {
+      total,
+      success: byStatus["success"] ?? 0,
+      processing:
+        (byStatus["processing"] ?? 0) + (byStatus["action-required"] ?? 0),
+      failed: (byStatus["failed"] ?? 0) + (byStatus["canceled"] ?? 0),
+      refunded: byStatus["refunded"] ?? 0,
+      paidAmount: Number(paidAgg?.sum ?? 0),
+    };
+  }
+
+  /**
+   * Open a gateway intent for a caller-supplied amount/reference and project it
+   * locally. Returns the intent id (so billing can correlate the invoice) plus
+   * the client action. When the provider settles synchronously, the intent is
+   * marked paid WITHOUT emitting — the caller (billing) settles inline after it
+   * has stored the intent id, avoiding a settle-before-correlation race.
+   */
+  async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
+    const snapshot = await this.paymentClient.initiate({
+      service: PaymentServiceEnum.FREIGHT,
+      referenceType: PaymentReferenceType.SHIPMENT,
+      referenceId: input.referenceId,
+      orderRef: input.orderRef,
+      amountMinor: input.amountMinor,
+      currency: input.currency,
+      provider: input.method as ProviderMethod,
+      platform: input.platform,
+      payerAccount: input.payerAccount,
+      returnUrl:
+        input.returnUrl ?? "https://edrfreight.triaplc.com/payment/success",
+      failureUrl:
+        input.failureUrl ?? "https://edrfreight.triaplc.com/payment/failure",
+    });
+
+    const immediateSuccess =
+      snapshot.status === ProviderPaymentStatus.SUCCEEDED;
+    const paidAt = snapshot.paidAt ? new Date(snapshot.paidAt) : undefined;
+
+    const intent = await this.upsertIntent(input, snapshot);
+
+    if (immediateSuccess) {
+      // Settle the projection but DO NOT notify billing — billing settles
+      // inline once it has stored intentId on the invoice (see payInvoice),
+      // avoiding a settle-before-correlation race.
+      await this.markIntentSucceeded(intent.id, {
+        providerTxnId: snapshot.providerTxnId,
+        paidAt,
+        notify: false,
+      });
+    }
+
+    return {
+      intentId: intent.id,
+      // `intent` still reflects the projection status ("processing" on immediate
+      // success — settlement is applied by the caller, not shown synchronously).
+      response: this.formatIntentResponse(intent),
+      immediateSuccess,
+      providerTxnId: snapshot.providerTxnId,
+      paidAt,
+    };
+  }
+
+  /** Create or update the local intent projection from a provider snapshot. */
+  private async upsertIntent(
+    input: InitiateIntentInput,
+    snapshot: PaymentIntentSnapshot,
+  ): Promise<PaymentEntity> {
+    const existing = await this.paymentRepo.findOneBy({
+      refId: input.referenceId,
+    });
+
+    const method: PaymentEntity["method"] =
+      PROVIDER_TO_METHOD[snapshot.provider ?? ""] ?? "telebirr";
+    const status =
+      snapshot.status === ProviderPaymentStatus.SUCCEEDED
+        ? "processing"
+        : this.toLocalStatus(snapshot.status);
+
+    const clientAction = (snapshot.clientAction ?? undefined) as
+      | Record<string, unknown>
+      | undefined;
+    const data = {
+      status,
+      method,
+      merchantOrderId:
+        snapshot.merchantOrderId ?? existing?.merchantOrderId ?? "",
+      transactionId: snapshot.providerTxnId ?? existing?.transactionId,
+      expiresAt: snapshot.expiresAt
+        ? new Date(snapshot.expiresAt)
+        : existing?.expiresAt,
+      failerCode: snapshot.failureCode ?? undefined,
+      failureMessage: snapshot.failureMessage ?? undefined,
+    };
+
+    if (existing) {
+      await this.paymentRepo.update({ id: existing.id }, {
+        ...data,
+        clientAction,
+      } as any);
+      return { ...existing, ...data, clientAction } as PaymentEntity;
+    }
+
+    return this.paymentRepo.create({
+      refId: input.referenceId,
+      type: input.source,
+      referenceType: input.referenceType,
+      amount: input.amountMinor,
+      currency: input.currency as PaymentEntity["currency"],
+      reason: input.reason ?? `Payment for ${input.orderRef}`,
+      rawInitiation: snapshot as unknown as Record<string, unknown>,
+      clientAction: clientAction ?? {},
+      ...data,
+    } as any);
+  }
+
+  /**
+   * Reconcile an intent's status with the gateway by reference. Read-only on the
+   * domain side: it syncs the local projection and, when the provider reports a
+   * newly-observed success, notifies billing to settle. `referenceId` is opaque
+   * (the booking id, but this service does not load it).
+   */
+  async getIntentByBookingId(referenceId: string): Promise<IntentStatusDto> {
+    const local = await this.paymentRepo.findOneBy({ refId: referenceId });
+
+    let snapshot: PaymentIntentSnapshot | null = null;
+    try {
+      snapshot = await this.paymentClient.getIntentByReference(
+        (local?.referenceType as PaymentReferenceType) ??
+        PaymentReferenceType.SHIPMENT,
+        referenceId,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn(
+        `payment service lookup failed for reference ${referenceId}: ${message}; using local intent`,
+      );
+    }
+
+    if (!snapshot) {
+      if (!local) throw new NotFoundException("PaymentIntent not found");
+      return this.formatIntentStatus(local);
+    }
+    if (!local) throw new NotFoundException("PaymentIntent not found");
+
+    // Sync local projection with provider-reported status.
+    const becameSuccess =
+      snapshot.status === ProviderPaymentStatus.SUCCEEDED &&
+      local.status !== "success";
+
+    if (becameSuccess) {
+      await this.markIntentSucceeded(local.id, {
+        providerTxnId: snapshot.providerTxnId,
+        paidAt: snapshot.paidAt ? new Date(snapshot.paidAt) : undefined,
+        notify: true,
+      });
+    } else if (snapshot.status !== ProviderPaymentStatus.SUCCEEDED) {
+      await this.paymentRepo.update(
+        { id: local.id },
+        {
+          status: this.toLocalStatus(snapshot.status),
+          failerCode: snapshot.failureCode ?? undefined,
+          failureMessage: snapshot.failureMessage ?? undefined,
+        },
+      );
+    }
+
+    const refreshed = await this.paymentRepo.findOneBy({ id: local.id });
+    return this.formatIntentStatus(refreshed ?? local);
+  }
+
+  /**
+   * Mark a gateway intent paid and (by default) notify billing to settle the
+   * linked invoice. Idempotent — no-op when already success. Pass `notify: false`
+   * when the caller settles inline and will trigger settlement itself.
+   */
+  async markIntentSucceeded(
+    intentId: string,
+    opts: { providerTxnId?: string; paidAt?: Date; notify?: boolean } = {},
+  ): Promise<{ alreadyFinalized: boolean }> {
+    const intent = await this.paymentRepo.findOneBy({ id: intentId });
+    if (!intent) throw new NotFoundException("PaymentIntent not found");
+    if (intent.status === "success") return { alreadyFinalized: true };
+
+    const paidAt = opts.paidAt ?? new Date();
+    await this.paymentRepo.update(
+      { id: intent.id },
+      {
+        status: "success",
+        paidAt,
+        transactionId: opts.providerTxnId ?? intent.transactionId,
+      },
+    );
+
+    if (opts.notify !== false) {
+      await this.billing.settleByPaymentId(
+        intent.id,
+        opts.providerTxnId,
+        paidAt,
+      );
+    }
+
+    return { alreadyFinalized: false };
+  }
+
+  async markPaymentFailed(input: {
+    intentId: string;
+    failureCode?: string;
+    failureMessage?: string;
+  }): Promise<void> {
+    const intent = await this.paymentRepo.findOneBy({ id: input.intentId });
+    if (!intent) throw new NotFoundException("PaymentIntent not found");
+    if (intent.status === "success" || intent.status === "canceled") return;
+
+    await this.paymentRepo.update(
+      { id: intent.id },
+      {
+        status: "failed",
+        failerCode: input.failureCode,
+        failureMessage: input.failureMessage,
+      },
+    );
+
+    // Invoice stays open for retry — nothing to settle. Logged only.
+    this.logger.warn(
+      `Payment ${intent.id} failed for ${intent.refId}` +
+      (input.failureMessage ? `: ${input.failureMessage}` : ""),
+    );
+  }
+
+  async refund(dto: RefundDto) {
+    const intent = await this.paymentRepo.findOneBy({
+      refId: dto.bookingId,
+      type: "booking",
+    });
+    if (!intent || intent.status !== "success") {
+      throw new BadRequestException("No successful payment to refund");
+    }
+
+    // NOTE: refunding still mutates the booking directly — left intact pending
+    // the refund redesign. TODO: route refunds through billing.refundPayable +
+    // a `${source}.invoice.refunded` reaction, like settlement.
+    await this.datasource.transaction(async (mg) => {
+      await mg.update(
+        PaymentEntity,
+        { id: intent.id },
+        { status: "refunded", refundedAt: new Date() },
+      );
+      await mg.update(
+        Booking,
+        { id: dto.bookingId },
+        { paymentStatus: "FAILED", status: "CANCELLED" },
+      );
+    });
+
+    return { refunded: true, bookingId: dto.bookingId };
+  }
+
+  async getActivePaymentByOrderIdAndMethod(
+    orderId: string,
+    method: PaymentEntity["method"],
+  ): Promise<PaymentEntity | null> {
+    return this.paymentRepo.getActivePaymentByOrderIdAndMethod(orderId, method);
+  }
+
+  async genReceiptHtml(orderId: string) {
+    const payment = await this.paymentRepo.findOneBy({
+      merchantOrderId: orderId,
+      status: "success",
+    });
+    if (!payment)
+      throw new BadRequestException(
+        "No successful payment found for this order",
+      );
+
+    const filePath = path.join(__dirname, "templates", "receipt.hbs");
+    if (!fs.existsSync(filePath)) throw new InternalServerErrorException();
+
+    const source = fs.readFileSync(filePath, "utf8");
+    const template = Handlebars.compile(source);
+    return template({
+      vendorName: "Ethio Djibouti Railway Freight Booking",
+      vendorAddress: "Addis Ababa",
+      receiptDate: payment.paidAt,
+      paymentMethod: payment.method,
+      subtotal: payment.amount.toString(),
+      total: payment.amount.toString(),
+      currency: payment.currency,
+      reason: payment.reason,
+    });
+  }
+
+  findBookingById(id: string) {
+    return this.paymentRepo.findOneBy({ refId: id });
+  }
+
+  formatIntentResponse(intent: PaymentEntity): InitiateResponseDto {
+    const clientAction =
+      intent.clientAction && typeof intent.clientAction === "object"
+        ? (intent.clientAction as unknown as ClientAction)
+        : undefined;
+    return {
+      intentId: intent.id,
+      status: STATUS_MAP[intent.status] ?? ProviderPaymentStatus.PROCESSING,
+      clientAction,
+      merchantOrderId: intent.merchantOrderId ?? undefined,
+    };
+  }
+
+  private formatIntentStatus(intent: PaymentEntity): IntentStatusDto {
+    return {
+      ...this.formatIntentResponse(intent),
+      paidAt: intent.paidAt?.toISOString(),
+      failureCode: intent.failerCode ?? undefined,
+      failureMessage: intent.failureMessage ?? undefined,
+    };
+  }
+
+  async handlePaymentEvent(event: {
+    eventType: string;
+    eventId: string;
+    referenceId: string;
+    intentId: string;
+    providerTxnId?: string;
+    paidAt?: string;
+    failureCode?: string;
+    failureMessage?: string;
+  }): Promise<{
+    processed: boolean;
+    alreadyFinalized?: boolean;
+    reason?: string;
+  }> {
+    console.log(`Received payment event: ${JSON.stringify(event)}`);
+    if (event.eventType === "payment.succeeded") {
+      const intent = await this.paymentRepo.findOneBy({
+        refId: event.referenceId,
+      });
+      if (!intent) {
         return {
-            items: items.map((p) => ({
-                id: p.id,
-                bookingId: p.refId,
-                amount: p.amount,
-                currency: p.currency,
-                method: p.method,
-                status: p.status,
-                merchantOrderId: p.merchantOrderId,
-                paidAt: p.paidAt,
-                createdAt: p.createdAt,
-            })),
-            total,
-            page,
-            pageSize,
+          processed: false,
+          reason: `No local intent for reference ${event.referenceId}`,
         };
-    }
+      }
+      console.log(`Processing payment succeeded event for intent: }`, intent);
+      const { alreadyFinalized } = await this.markIntentSucceeded(intent.id, {
+        providerTxnId: event.providerTxnId,
+        paidAt: event.paidAt ? new Date(event.paidAt) : undefined,
+        notify: true,
+      });
+      console.log(
+        `Payment finalized for intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`,
+      );
 
-    /** Aggregate counts across ALL payments for the dashboard summary cards. */
-    async getSummary() {
-        const rows = await this.paymentRepo
-            .createQueryBuilder("payment")
-            .select("payment.status", "status")
-            .addSelect("COUNT(*)::int", "count")
-            .groupBy("payment.status")
-            .getRawMany<{ status: string; count: number }>();
-
-        const byStatus: Record<string, number> = {};
-        let total = 0;
-        for (const row of rows) {
-            byStatus[row.status] = row.count;
-            total += row.count;
-        }
-
-        const paidAgg = await this.paymentRepo
-            .createQueryBuilder("payment")
-            .select("COALESCE(SUM(payment.amount), 0)", "sum")
-            .where("payment.status = :status", { status: "success" })
-            .getRawOne<{ sum: string }>();
-
-        return {
-            total,
-            success: byStatus["success"] ?? 0,
-            processing:
-                (byStatus["processing"] ?? 0) + (byStatus["action-required"] ?? 0),
-            failed: (byStatus["failed"] ?? 0) + (byStatus["canceled"] ?? 0),
-            refunded: byStatus["refunded"] ?? 0,
-            paidAmount: Number(paidAgg?.sum ?? 0),
-        };
-    }
-
-    /**
-     * Open a gateway intent for a caller-supplied amount/reference and project it
-     * locally. Returns the intent id (so billing can correlate the invoice) plus
-     * the client action. When the provider settles synchronously, the intent is
-     * marked paid WITHOUT emitting — the caller (billing) settles inline after it
-     * has stored the intent id, avoiding a settle-before-correlation race.
-     */
-    async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
-        const snapshot = await this.paymentClient.initiate({
-            service: PaymentServiceEnum.FREIGHT,
-            referenceType: input.referenceType,
-            referenceId: input.referenceId,
-            orderRef: input.orderRef,
-            amountMinor: input.amountMinor,
-            currency: input.currency,
-            provider: input.method as ProviderMethod,
-            platform: input.platform,
-            payerAccount: input.payerAccount,
-            returnUrl: input.returnUrl ?? "https://edrfreight.triaplc.com/payment/success",
-            failureUrl: input.failureUrl ?? "https://edrfreight.triaplc.com/payment/failure",
-        });
-
-        const immediateSuccess = snapshot.status === ProviderPaymentStatus.SUCCEEDED;
-        const paidAt = snapshot.paidAt ? new Date(snapshot.paidAt) : undefined;
-
-        const intent = await this.upsertIntent(input, snapshot);
-
-        if (immediateSuccess) {
-            // Settle the projection but DO NOT notify billing — billing settles
-            // inline once it has stored intentId on the invoice (see payInvoice),
-            // avoiding a settle-before-correlation race.
-            await this.markIntentSucceeded(intent.id, {
-                providerTxnId: snapshot.providerTxnId,
-                paidAt,
-                notify: false,
-            });
-        }
-
-        return {
-            intentId: intent.id,
-            // `intent` still reflects the projection status ("processing" on immediate
-            // success — settlement is applied by the caller, not shown synchronously).
-            response: this.formatIntentResponse(intent),
-            immediateSuccess,
-            providerTxnId: snapshot.providerTxnId,
-            paidAt,
-        };
-    }
-
-    /** Create or update the local intent projection from a provider snapshot. */
-    private async upsertIntent(
-        input: InitiateIntentInput,
-        snapshot: PaymentIntentSnapshot,
-    ): Promise<PaymentEntity> {
-        const existing = await this.paymentRepo.findOneBy({
-            refId: input.referenceId,
-        });
-
-        const method: PaymentEntity["method"] =
-            PROVIDER_TO_METHOD[snapshot.provider ?? ""] ?? "telebirr";
-        const status =
-            snapshot.status === ProviderPaymentStatus.SUCCEEDED
-                ? "processing"
-                : this.toLocalStatus(snapshot.status);
-
-        const clientAction = (snapshot.clientAction ?? undefined) as
-            | Record<string, unknown>
-            | undefined;
-        const data = {
-            status,
-            method,
-            merchantOrderId: snapshot.merchantOrderId ?? existing?.merchantOrderId ?? "",
-            transactionId: snapshot.providerTxnId ?? existing?.transactionId,
-            expiresAt: snapshot.expiresAt ? new Date(snapshot.expiresAt) : existing?.expiresAt,
-            failerCode: snapshot.failureCode ?? undefined,
-            failureMessage: snapshot.failureMessage ?? undefined,
-        };
-
-        if (existing) {
-            await this.paymentRepo.update({ id: existing.id }, { ...data, clientAction } as any);
-            return { ...existing, ...data, clientAction } as PaymentEntity;
-        }
-
-        return this.paymentRepo.create({
-            refId: input.referenceId,
-            type: input.source,
-            referenceType: input.referenceType,
-            amount: input.amountMinor,
-            currency: input.currency as PaymentEntity["currency"],
-            reason: input.reason ?? `Payment for ${input.orderRef}`,
-            rawInitiation: snapshot as unknown as Record<string, unknown>,
-            clientAction: clientAction ?? {},
-            ...data,
-        } as any);
-    }
-
-    /**
-     * Reconcile an intent's status with the gateway by reference. Read-only on the
-     * domain side: it syncs the local projection and, when the provider reports a
-     * newly-observed success, notifies billing to settle. `referenceId` is opaque
-     * (the booking id, but this service does not load it).
-     */
-    async getIntentByBookingId(referenceId: string): Promise<IntentStatusDto> {
-        const local = await this.paymentRepo.findOneBy({ refId: referenceId });
-
-        let snapshot: PaymentIntentSnapshot | null = null;
-        try {
-            snapshot = await this.paymentClient.getIntentByReference(
-                (local?.referenceType as PaymentReferenceType) ?? PaymentReferenceType.SHIPMENT,
-                referenceId,
-            );
-        } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.logger.warn(
-                `payment service lookup failed for reference ${referenceId}: ${message}; using local intent`,
-            );
-        }
-
-        if (!snapshot) {
-            if (!local) throw new NotFoundException("PaymentIntent not found");
-            return this.formatIntentStatus(local);
-        }
-        if (!local) throw new NotFoundException("PaymentIntent not found");
-
-        // Sync local projection with provider-reported status.
-        const becameSuccess =
-            snapshot.status === ProviderPaymentStatus.SUCCEEDED && local.status !== "success";
-
-        if (becameSuccess) {
-            await this.markIntentSucceeded(local.id, {
-                providerTxnId: snapshot.providerTxnId,
-                paidAt: snapshot.paidAt ? new Date(snapshot.paidAt) : undefined,
-                notify: true,
-            });
-        } else if (snapshot.status !== ProviderPaymentStatus.SUCCEEDED) {
-            await this.paymentRepo.update(
-                { id: local.id },
-                {
-                    status: this.toLocalStatus(snapshot.status),
-                    failerCode: snapshot.failureCode ?? undefined,
-                    failureMessage: snapshot.failureMessage ?? undefined,
-                },
-            );
-        }
-
-        const refreshed = await this.paymentRepo.findOneBy({ id: local.id });
-        return this.formatIntentStatus(refreshed ?? local);
-    }
-
-    /**
-     * Mark a gateway intent paid and (by default) notify billing to settle the
-     * linked invoice. Idempotent — no-op when already success. Pass `notify: false`
-     * when the caller settles inline and will trigger settlement itself.
-     */
-    async markIntentSucceeded(
-        intentId: string,
-        opts: { providerTxnId?: string; paidAt?: Date; notify?: boolean } = {},
-    ): Promise<{ alreadyFinalized: boolean }> {
-        const intent = await this.paymentRepo.findOneBy({ id: intentId });
-        if (!intent) throw new NotFoundException("PaymentIntent not found");
-        if (intent.status === "success") return { alreadyFinalized: true };
-
-        const paidAt = opts.paidAt ?? new Date();
-        await this.paymentRepo.update(
-            { id: intent.id },
-            { status: "success", paidAt, transactionId: opts.providerTxnId ?? intent.transactionId },
+      // When the intent references a booking, flip the booking itself paid.
+      // refId holds the booking id (the domain reference the intent opened with).
+      if (intent.referenceType === PaymentReferenceType.BOOKING) {
+        await this.datasource.manager.update(
+          Booking,
+          { id: intent.refId },
+          { status: "PAID", paymentStatus: "PAID" },
         );
-
-        if (opts.notify !== false) {
-            await this.billing.settleByPaymentId(intent.id, opts.providerTxnId, paidAt);
-        }
-
-        return { alreadyFinalized: false };
+      }
+      // console.log(`Payment finalized for booking ${event.referenceId}, intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
+      return { processed: true, alreadyFinalized };
     }
 
-    async markPaymentFailed(input: {
-        intentId: string;
-        failureCode?: string;
-        failureMessage?: string;
-    }): Promise<void> {
-        const intent = await this.paymentRepo.findOneBy({ id: input.intentId });
-        if (!intent) throw new NotFoundException("PaymentIntent not found");
-        if (intent.status === "success" || intent.status === "canceled") return;
-
-        await this.paymentRepo.update(
-            { id: intent.id },
-            { status: "failed", failerCode: input.failureCode, failureMessage: input.failureMessage },
-        );
-
-        // Invoice stays open for retry — nothing to settle. Logged only.
-        this.logger.warn(
-            `Payment ${intent.id} failed for ${intent.refId}` +
-            (input.failureMessage ? `: ${input.failureMessage}` : ""),
-        );
-    }
-
-    async refund(dto: RefundDto) {
-        const intent = await this.paymentRepo.findOneBy({ refId: dto.bookingId, type: "booking" });
-        if (!intent || intent.status !== "success") {
-            throw new BadRequestException("No successful payment to refund");
-        }
-
-        // NOTE: refunding still mutates the booking directly — left intact pending
-        // the refund redesign. TODO: route refunds through billing.refundPayable +
-        // a `${source}.invoice.refunded` reaction, like settlement.
-        await this.datasource.transaction(async (mg) => {
-            await mg.update(PaymentEntity, { id: intent.id }, { status: "refunded", refundedAt: new Date() });
-            await mg.update(Booking, { id: dto.bookingId }, { paymentStatus: "FAILED", status: "CANCELLED" });
-        });
-
-        return { refunded: true, bookingId: dto.bookingId };
-    }
-
-    async getActivePaymentByOrderIdAndMethod(orderId: string, method: PaymentEntity["method"]): Promise<PaymentEntity | null> {
-        return this.paymentRepo.getActivePaymentByOrderIdAndMethod(orderId, method);
-    }
-
-    async genReceiptHtml(orderId: string) {
-        const payment = await this.paymentRepo.findOneBy({ merchantOrderId: orderId, status: "success" });
-        if (!payment) throw new BadRequestException("No successful payment found for this order");
-
-        const filePath = path.join(__dirname, "templates", "receipt.hbs");
-        if (!fs.existsSync(filePath)) throw new InternalServerErrorException();
-
-        const source = fs.readFileSync(filePath, "utf8");
-        const template = Handlebars.compile(source);
-        return template({
-            vendorName: "Ethio Djibouti Railway Freight Booking",
-            vendorAddress: "Addis Ababa",
-            receiptDate: payment.paidAt,
-            paymentMethod: payment.method,
-            subtotal: payment.amount.toString(),
-            total: payment.amount.toString(),
-            currency: payment.currency,
-            reason: payment.reason,
-        });
-    }
-
-    findBookingById(id: string) {
-        return this.paymentRepo.findOneBy({ refId: id });
-    }
-
-    formatIntentResponse(intent: PaymentEntity): InitiateResponseDto {
-        const clientAction =
-            intent.clientAction && typeof intent.clientAction === "object"
-                ? (intent.clientAction as unknown as ClientAction)
-                : undefined;
+    if (event.eventType === "payment.failed") {
+      const intent = await this.paymentRepo.findOneBy({
+        refId: event.referenceId,
+      });
+      if (!intent) {
         return {
-            intentId: intent.id,
-            status: STATUS_MAP[intent.status] ?? ProviderPaymentStatus.PROCESSING,
-            clientAction,
-            merchantOrderId: intent.merchantOrderId ?? undefined,
+          processed: false,
+          reason: `No local intent for reference ${event.referenceId}`,
         };
+      }
+      await this.markPaymentFailed({
+        intentId: intent.id,
+        failureCode: event.failureCode,
+        failureMessage: event.failureMessage,
+      });
+      return { processed: true };
     }
 
-    private formatIntentStatus(intent: PaymentEntity): IntentStatusDto {
-        return {
-            ...this.formatIntentResponse(intent),
-            paidAt: intent.paidAt?.toISOString(),
-            failureCode: intent.failerCode ?? undefined,
-            failureMessage: intent.failureMessage ?? undefined,
-        };
+    return {
+      processed: false,
+      reason: `Unknown event type: ${event.eventType}`,
+    };
+  }
+
+  private toLocalStatus(
+    status: ProviderPaymentStatus,
+  ): PaymentEntity["status"] {
+    switch (status) {
+      case ProviderPaymentStatus.SUCCEEDED:
+        return "success";
+      case ProviderPaymentStatus.FAILED:
+        return "failed";
+      case ProviderPaymentStatus.CANCELLED:
+        return "canceled";
+      case ProviderPaymentStatus.PROCESSING:
+        return "processing";
+      default:
+        return "action-required";
     }
+  }
 
-    async handlePaymentEvent(event: {
-        eventType: string;
-        eventId: string;
-        referenceId: string;
-        intentId: string;
-        providerTxnId?: string;
-        paidAt?: string;
-        failureCode?: string;
-        failureMessage?: string;
-    }): Promise<{ processed: boolean; alreadyFinalized?: boolean; reason?: string }> {
-        console.log(`Received payment event: ${JSON.stringify(event)}`);
-        if (event.eventType === "payment.succeeded") {
-            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId });
-            if (!intent) {
-                return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
-            }
-            console.log(`Processing payment succeeded event for intent: }`,intent);
-            const { alreadyFinalized } = await this.markIntentSucceeded(intent.id, {
-                providerTxnId: event.providerTxnId,
-                paidAt: event.paidAt ? new Date(event.paidAt) : undefined,
-                notify: true,
-            });
-            console.log(`Payment finalized for intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
-
-            // When the intent references a booking, flip the booking itself paid.
-            // refId holds the booking id (the domain reference the intent opened with).
-            if (intent.referenceType === PaymentReferenceType.BOOKING) {
-                await this.datasource.manager.update(
-                    Booking,
-                    { id: intent.refId },
-                    { status: "PAID", paymentStatus: "PAID" },
-                );
-            }
-            // console.log(`Payment finalized for booking ${event.referenceId}, intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
-            return { processed: true, alreadyFinalized };
-        }
-
-        if (event.eventType === "payment.failed") {
-            const intent = await this.paymentRepo.findOneBy({ refId: event.referenceId });
-            if (!intent) {
-                return { processed: false, reason: `No local intent for reference ${event.referenceId}` };
-            }
-            await this.markPaymentFailed({
-                intentId: intent.id,
-                failureCode: event.failureCode,
-                failureMessage: event.failureMessage,
-            });
-            return { processed: true };
-        }
-
-        return { processed: false, reason: `Unknown event type: ${event.eventType}` };
-    }
-
-    private toLocalStatus(status: ProviderPaymentStatus): PaymentEntity["status"] {
-        switch (status) {
-            case ProviderPaymentStatus.SUCCEEDED: return "success";
-            case ProviderPaymentStatus.FAILED: return "failed";
-            case ProviderPaymentStatus.CANCELLED: return "canceled";
-            case ProviderPaymentStatus.PROCESSING: return "processing";
-            default: return "action-required";
-        }
-    }
-
-    async findByCompanyId(companyId: string) {
-        return this.paymentRepo.findByCompanyId(companyId);
-    }
+  async findByCompanyId(companyId: string) {
+    return this.paymentRepo.findByCompanyId(companyId);
+  }
 }

From 5ad4efd7eb7bd1b5d1d60779ed67df4bbfbe1137 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 11:58:28 +0000
Subject: [PATCH 53/63] feat: add pdf to the central invoice system

---
 .../src/modules/billing/billing.module.ts     |   2 +
 .../modules/billing/billing.service.spec.ts   |   6 +
 .../src/modules/billing/billing.service.ts    |  95 +++++--
 .../billing/documents/documents.module.ts     |  16 ++
 .../documents/invoice-document.service.ts     | 179 +++++++++++++
 .../billing/documents/pdf-render.service.ts   | 160 ++++++++++++
 .../modules/billing/invoice-numbering.util.ts |  44 ++++
 .../billing/invoice-settlement.util.ts        |  36 +++
 .../warehouses/warehouse-invoice.service.ts   | 240 ++++++------------
 .../warehouse-release-document.service.ts     | 104 +-------
 .../modules/warehouses/warehouses.module.ts   |   2 +
 11 files changed, 618 insertions(+), 266 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/invoice-numbering.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 551fae6bf..dc78cd6e9 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -4,6 +4,7 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 import { BillingController } from "./billing.controller";
 import { PortalBillingController } from "./portal-billing.controller";
 import { BillingService } from "./billing.service";
+import { DocumentsModule } from "./documents/documents.module";
 import { Invoice } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
@@ -16,6 +17,7 @@ import { CompaniesModule } from "../companies/companies.module";
     TypeOrmModule.forFeature([Invoice, InvoiceLine]),
     forwardRef(() => PaymentModule),
     CompaniesModule,
+    DocumentsModule,
   ],
   controllers: [BillingController, PortalBillingController],
   providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 5d407d3cd..e52dfafa1 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -76,6 +76,7 @@ describe("BillingService.generateInvoice", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
   });
 
@@ -134,6 +135,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -171,6 +173,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -194,6 +197,7 @@ describe("BillingService.recordPayment", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
     return { service, mg, events };
   }
@@ -282,6 +286,7 @@ describe("BillingService.settlePayable", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
 
     const settled = await service.settlePayable(
@@ -316,6 +321,7 @@ describe("BillingService.settlePayable", () => {
       events as never,
       {} as never, // payment
       {} as never, // companies
+      {} as never, // invoiceDocuments
     );
 
     const settled = await service.settlePayable(
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index ce4341486..edacc2c79 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -14,6 +14,12 @@ import { Invoice, InvoicePayment } from "./entities/invoice.entity";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
+import { nextDailyInvoiceNumber } from "./invoice-numbering.util";
+import { applySettlement, round2 } from "./invoice-settlement.util";
+import {
+  InvoiceDocumentModel,
+  InvoiceDocumentService,
+} from "./documents/invoice-document.service";
 import { PaymentService } from "../payment/payment.service";
 import { InitiateResponseDto } from "../payment/payments.dto";
 import { CompaniesService } from "../companies/companies.service";
@@ -50,9 +56,6 @@ const OPEN_STATUSES: Freight.InvoiceStatus[] = [
   Freight.InvoiceStatus.Overdue,
 ];
 
-/** Round to 2 decimals, avoiding binary float drift. */
-const round2 = (n: number): number => Math.round(n * 100) / 100;
-
 /** A single line to bill on a generated invoice. */
 export interface InvoiceLineInput {
   chargeType: string;
@@ -122,6 +125,7 @@ export class BillingService {
     @Inject(forwardRef(() => PaymentService))
     private readonly payment: PaymentService,
     private readonly companies: CompaniesService,
+    private readonly invoiceDocuments: InvoiceDocumentService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -142,6 +146,69 @@ export class BillingService {
     return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
   }
 
+  // ── Documents (central PDF) ──────────────────────────────────────────────────
+
+  /** Sealed PDF invoice for any source, rendered by the shared document service. */
+  async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
+    const invoice = await this.findById(id);
+    return this.invoiceDocuments.render(this.toDocumentModel(invoice, "INVOICE"));
+  }
+
+  /** Sealed PDF receipt; available once any payment has been recorded. */
+  async receipt(id: string): Promise<{ filename: string; buffer: Buffer }> {
+    const invoice = await this.findById(id);
+    if (Number(invoice.paidAmount) <= 0) {
+      throw new BadRequestException("A receipt is available only after payment is recorded.");
+    }
+    return this.invoiceDocuments.render(this.toDocumentModel(invoice, "RECEIPT"));
+  }
+
+  /** Map a global invoice (+ lines) onto the source-agnostic document model. */
+  private toDocumentModel(
+    invoice: Invoice & { lines: InvoiceLine[] },
+    kind: "INVOICE" | "RECEIPT",
+  ): InvoiceDocumentModel {
+    const title = invoice.source
+      ? invoice.source.charAt(0).toUpperCase() + invoice.source.slice(1)
+      : "EDR";
+    const totals: InvoiceDocumentModel["totals"] = [
+      { label: "Subtotal", amount: Number(invoice.subtotalAmount) },
+    ];
+    if (Number(invoice.taxAmount) > 0) {
+      totals.push({ label: "Tax", amount: Number(invoice.taxAmount) });
+    }
+    totals.push({ label: "Total", amount: Number(invoice.totalAmount), grand: true });
+    totals.push({ label: "Paid", amount: Number(invoice.paidAmount) });
+    totals.push({ label: "Balance", amount: Number(invoice.balanceAmount) });
+
+    return {
+      kind,
+      title,
+      documentNumber: invoice.invoiceNumber,
+      issuedAt: invoice.issuedAt ?? invoice.createdAt,
+      status: invoice.status,
+      currency: invoice.currency,
+      summary: [
+        { label: "Status", value: invoice.status },
+        { label: "Type", value: invoice.type },
+        { label: "Reference", value: invoice.sourceId },
+        { label: "Currency", value: invoice.currency },
+        { label: "Issued", value: invoice.issuedAt ? new Date(invoice.issuedAt).toLocaleDateString("en-GB") : null },
+        { label: "Due", value: invoice.dueAt ? new Date(invoice.dueAt).toLocaleDateString("en-GB") : null },
+      ],
+      categoryHeader: "Charge type",
+      lines: invoice.lines.map((l) => ({
+        description: l.description ?? l.chargeType,
+        category: l.chargeType,
+        quantity: l.quantity,
+        unitRate: l.unitRate,
+        amount: l.amount,
+        currency: l.currency,
+      })),
+      totals,
+    };
+  }
+
   // ── Customer-scoped reads (portal) ───────────────────────────────────────────
 
   /** Resolve the customer's company id from their IAM user id (null if none). */
@@ -203,17 +270,8 @@ export class BillingService {
   // ── Generation ───────────────────────────────────────────────────────────────
 
   /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */
-  private async nextInvoiceNumber(mg: EntityManager): Promise<string> {
-    const now = new Date();
-    const ymd = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, "0")}${String(now.getDate()).padStart(2, "0")}`;
-    const prefix = `FRT-${ymd}-`;
-    const [row] = await mg.query(
-      `SELECT COALESCE(MAX(CAST(split_part(invoice_number, '-', 3) AS int)), 0) AS seq
-         FROM freight.invoices WHERE invoice_number LIKE $1`,
-      [`${prefix}%`],
-    );
-    const next = Number(row?.seq ?? 0) + 1;
-    return `${prefix}${String(next).padStart(5, "0")}`;
+  private nextInvoiceNumber(mg: EntityManager): Promise<string> {
+    return nextDailyInvoiceNumber(mg, { table: "freight.invoices", code: "FRT" });
   }
 
   /**
@@ -365,10 +423,11 @@ export class BillingService {
     }
 
     const at = input.paidAt ?? new Date();
-    const total = Number(invoice.totalAmount);
-    const paidAmount = round2(Number(invoice.paidAmount) + input.amount);
-    const balanceAmount = Math.max(0, round2(total - paidAmount));
-    const fullyPaid = paidAmount >= total;
+    const { paidAmount, balanceAmount, fullyPaid } = applySettlement(
+      invoice.totalAmount,
+      invoice.paidAmount,
+      input.amount,
+    );
     const status = fullyPaid
       ? Freight.InvoiceStatus.Paid
       : Freight.InvoiceStatus.PartiallyPaid;
diff --git a/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
new file mode 100644
index 000000000..c320a5d44
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
@@ -0,0 +1,16 @@
+import { Module } from "@nestjs/common";
+
+import { InvoiceDocumentService } from "./invoice-document.service";
+import { PdfRenderService } from "./pdf-render.service";
+
+/**
+ * Standalone document infrastructure — generic HTML→PDF plus the shared
+ * invoice/receipt renderer. Has no domain dependencies, so any module (billing,
+ * warehouses, …) can import it to print invoices without coupling to the
+ * billing payment graph.
+ */
+@Module({
+  providers: [PdfRenderService, InvoiceDocumentService],
+  exports: [PdfRenderService, InvoiceDocumentService],
+})
+export class DocumentsModule {}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
new file mode 100644
index 000000000..a07087f8f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -0,0 +1,179 @@
+import { Injectable } from "@nestjs/common";
+
+import { PdfRenderService } from "./pdf-render.service";
+
+export type InvoiceDocumentKind = "INVOICE" | "RECEIPT";
+
+/** One billed line on the document (charge type / fee type agnostic). */
+export interface InvoiceDocumentLine {
+  description: string | null;
+  /** Optional categorisation column (e.g. "Fee type" / "Charge type"). */
+  category?: string | null;
+  quantity?: number | null;
+  unitRate?: number | null;
+  amount?: number | null;
+  currency?: string | null;
+}
+
+/** A labelled total row in the totals box; mark `grand` for the headline total. */
+export interface InvoiceDocumentTotal {
+  label: string;
+  amount: number;
+  grand?: boolean;
+}
+
+/**
+ * Source-agnostic description of a printable invoice/receipt. Each billing
+ * source maps its own entity onto this shape; the renderer owns the layout so
+ * every EDR invoice document looks identical regardless of source.
+ */
+export interface InvoiceDocumentModel {
+  kind: InvoiceDocumentKind;
+  /** Document heading, e.g. "Warehouse Fee Invoice" / "Freight Invoice". */
+  title: string;
+  documentNumber: string;
+  issuedAt?: Date | string | null;
+  status: string;
+  currency: string;
+  /** Free-form summary grid (label/value pairs). */
+  summary: Array<{ label: string; value: string | null }>;
+  /** Header for the line-item category column; column hidden when omitted. */
+  categoryHeader?: string;
+  lines: InvoiceDocumentLine[];
+  totals: InvoiceDocumentTotal[];
+  /** Override the round seal text; defaults from kind/status. */
+  sealText?: string;
+}
+
+/**
+ * Central invoice/receipt PDF renderer shared by every billing source. Turns a
+ * {@link InvoiceDocumentModel} into the sealed EDR document HTML and renders it
+ * via {@link PdfRenderService}. Previously this layout lived (warehouse-only) in
+ * `WarehouseInvoiceService`; it now serves all invoices.
+ */
+@Injectable()
+export class InvoiceDocumentService {
+  constructor(private readonly pdf: PdfRenderService) {}
+
+  async render(
+    model: InvoiceDocumentModel,
+  ): Promise<{ filename: string; buffer: Buffer }> {
+    const html = this.buildHtml(model);
+    const kindLabel = model.kind === "RECEIPT" ? "receipt" : "invoice";
+    return {
+      filename: `${this.safeFilename(model.documentNumber)}-${kindLabel}.pdf`,
+      buffer: await this.pdf.htmlToPdfBuffer(html, { label: `${model.title} ${kindLabel}` }),
+    };
+  }
+
+  buildHtml(model: InvoiceDocumentModel): string {
+    const esc = (value: unknown) =>
+      String(value ?? "-")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+    const money = (amount: unknown, currency = model.currency) =>
+      `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
+    const date = (value: unknown) =>
+      value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
+
+    const showCategory = Boolean(model.categoryHeader);
+    const sealText =
+      model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
+
+    const summaryRows = model.summary
+      .map((row) => `<div><span>${esc(row.label)}</span>${esc(row.value)}</div>`)
+      .join("");
+
+    const itemRows = model.lines
+      .map(
+        (item) => `<tr>
+              <td>${esc(item.description)}</td>
+              ${showCategory ? `<td>${esc((item.category ?? "").replace(/_/g, " "))}</td>` : ""}
+              <td class="num">${esc(item.quantity ?? 0)}</td>
+              <td class="num">${esc(money(item.unitRate, item.currency ?? model.currency))}</td>
+              <td class="num">${esc(money(item.amount, item.currency ?? model.currency))}</td>
+            </tr>`,
+      )
+      .join("");
+
+    const totalRows = model.totals
+      .map(
+        (total) =>
+          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount))}</strong></div>`,
+      )
+      .join("");
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}</title>
+  <style>
+    body { font-family: Arial, sans-serif; color: #0f172a; margin: 0; }
+    .doc { padding: 16px 8px; position: relative; }
+    .top { display: flex; justify-content: space-between; gap: 24px; border-bottom: 3px solid #0f766e; padding-bottom: 16px; }
+    .brand { font-size: 13px; color: #475569; text-transform: uppercase; letter-spacing: .08em; }
+    h1 { margin: 8px 0 0; font-size: 30px; }
+    .meta { text-align: right; font-size: 12px; color: #475569; }
+    .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
+    .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
+    .summary { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 28px; margin: 24px 150px 16px 0; font-size: 13px; }
+    .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; }
+    .summary span { color: #64748b; display: block; font-size: 11px; margin-bottom: 3px; }
+    table { width: 100%; border-collapse: collapse; margin-top: 18px; }
+    th { text-align: left; background: #f8fafc; color: #475569; }
+    th, td { border: 1px solid #cbd5e1; padding: 9px 10px; font-size: 12px; }
+    td.num, th.num { text-align: right; }
+    .totals { margin-left: auto; width: 330px; margin-top: 18px; }
+    .total-row { display: flex; justify-content: space-between; border-bottom: 1px solid #e2e8f0; padding: 8px 0; font-size: 13px; }
+    .grand { font-size: 16px; font-weight: 800; }
+    .footer { margin-top: 34px; display: grid; grid-template-columns: 1fr 1fr; gap: 28px; }
+    .line { border-top: 1px solid #334155; padding-top: 8px; font-size: 12px; color: #475569; }
+  </style>
+</head>
+<body>
+  <div class="doc">
+    <div class="top">
+      <div>
+        <div class="brand">Ethio-Djibouti Railway S.C.</div>
+        <h1>${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}</h1>
+      </div>
+      <div class="meta">
+        Document no.
+        <strong>${esc(model.documentNumber)}</strong>
+        Issued: ${esc(date(model.issuedAt))}
+      </div>
+    </div>
+    <div class="seal">${esc(sealText)}</div>
+    <div class="summary">${summaryRows}</div>
+    <table>
+      <thead>
+        <tr>
+          <th>Description</th>
+          ${showCategory ? `<th>${esc(model.categoryHeader)}</th>` : ""}
+          <th class="num">Qty</th>
+          <th class="num">Rate</th>
+          <th class="num">Amount</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${itemRows}
+      </tbody>
+    </table>
+    <div class="totals">${totalRows}</div>
+    <div class="footer">
+      <div class="line">Prepared by EDR finance</div>
+      <div class="line">Authorized seal / signature</div>
+    </div>
+  </div>
+</body>
+</html>`;
+  }
+
+  safeFilename(value: string): string {
+    return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
new file mode 100644
index 000000000..447bc2516
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
@@ -0,0 +1,160 @@
+import { existsSync } from "fs";
+
+import { Injectable, InternalServerErrorException, Logger } from "@nestjs/common";
+
+const MIN_VALID_PDF_BYTES = 2_000;
+
+const PDF_PRINT_STYLES = `
+<style id="edr-pdf-print-fix">
+  @media print {
+    html, body {
+      background: #fff !important;
+      -webkit-print-color-adjust: exact;
+      print-color-adjust: exact;
+    }
+  }
+</style>`;
+
+export interface PdfRenderOptions {
+  /** Label used in logs to identify the document kind. */
+  label?: string;
+  /**
+   * Degraded renderer used when Chromium is unavailable. Receives the
+   * print-prepared HTML and must return a valid PDF buffer (≥ 2KB, `%PDF-`
+   * header). When omitted, a generic single-page fallback is produced.
+   */
+  fallback?: (preparedHtml: string) => Buffer;
+}
+
+/**
+ * Generic HTML → PDF renderer shared by every document producer (invoices,
+ * receipts, warehouse release orders). Renders via headless Chromium when
+ * available and degrades to a caller-supplied (or generic) hand-built PDF
+ * otherwise. This is pure infrastructure — it knows nothing about invoices.
+ */
+@Injectable()
+export class PdfRenderService {
+  private readonly logger = new Logger(PdfRenderService.name);
+
+  async htmlToPdfBuffer(html: string, opts: PdfRenderOptions = {}): Promise<Buffer> {
+    const label = opts.label ?? "document";
+    const preparedHtml = this.injectPdfPrintStyles(html);
+    const executablePath = this.resolveExecutablePath();
+
+    try {
+      const puppeteer = await import("puppeteer");
+      const launchOptions: import("puppeteer").LaunchOptions = {
+        headless: true,
+        args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
+        ...(executablePath ? { executablePath } : {}),
+      };
+
+      const browser = await puppeteer.default.launch(launchOptions);
+      try {
+        const page = await browser.newPage();
+        await page.setViewport({ width: 794, height: 1123, deviceScaleFactor: 1 });
+        await page.setContent(preparedHtml, { waitUntil: "load", timeout: 60_000 });
+        await page.emulateMediaType("print");
+        await new Promise((resolve) => setTimeout(resolve, 250));
+
+        const pdf = await page.pdf({
+          format: "A4",
+          printBackground: true,
+          margin: { top: "16mm", bottom: "18mm", left: "14mm", right: "14mm" },
+        });
+
+        const buffer = Buffer.from(pdf);
+        if (!this.isValidPdf(buffer)) {
+          throw new Error(`Puppeteer produced invalid ${label} PDF (${buffer.length} bytes)`);
+        }
+        this.logger.log(
+          `${label} PDF rendered (${buffer.length} bytes) via ${executablePath ?? "bundled Chromium"}`,
+        );
+        return buffer;
+      } finally {
+        await browser.close();
+      }
+    } catch (error) {
+      this.logger.error(`${label} PDF failed (executable=${executablePath ?? "default"}): ${error}`);
+      const fallback = (opts.fallback ?? ((h) => this.genericFallbackPdf(h)))(preparedHtml);
+      if (this.isValidPdf(fallback)) {
+        this.logger.warn(
+          `Using ${label} PDF fallback (${fallback.length} bytes). Install Chromium or set PUPPETEER_EXECUTABLE_PATH for full layout rendering.`,
+        );
+        return fallback;
+      }
+      throw new InternalServerErrorException(
+        `${label} PDF could not be generated. Ensure Chromium is installed or set PUPPETEER_EXECUTABLE_PATH.`,
+      );
+    }
+  }
+
+  private injectPdfPrintStyles(html: string): string {
+    if (html.includes("edr-pdf-print-fix")) return html;
+    if (html.includes("</head>")) {
+      return html.replace("</head>", `${PDF_PRINT_STYLES}</head>`);
+    }
+    return `${PDF_PRINT_STYLES}${html}`;
+  }
+
+  private resolveExecutablePath(): string | undefined {
+    const fromEnv = process.env.PUPPETEER_EXECUTABLE_PATH?.trim();
+    if (fromEnv && existsSync(fromEnv)) return fromEnv;
+
+    const candidates = [
+      "/usr/bin/chromium",
+      "/usr/bin/chromium-browser",
+      "/usr/bin/google-chrome-stable",
+      "/usr/bin/google-chrome",
+    ];
+    return candidates.find((path) => existsSync(path));
+  }
+
+  isValidPdf(buffer: Buffer): boolean {
+    return buffer.length >= MIN_VALID_PDF_BYTES && buffer.subarray(0, 5).toString("ascii") === "%PDF-";
+  }
+
+  /** Minimal valid one-page PDF carrying a plain-text rendering of the document. */
+  private genericFallbackPdf(html: string): Buffer {
+    const text = html
+      .replace(/<script[\s\S]*?<\/script>/gi, "")
+      .replace(/<style[\s\S]*?<\/style>/gi, "")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/&nbsp;/gi, " ")
+      .replace(/&amp;/gi, "&")
+      .replace(/&lt;/gi, "<")
+      .replace(/&gt;/gi, ">")
+      .replace(/[^\x20-\x7e]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 900);
+
+    const escape = (value: string) => value.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+    const lines = (text.match(/.{1,90}/g) ?? ["Document"]).slice(0, 40);
+    const stream =
+      "BT\n/F1 10 Tf\n36 800 Td\n12 TL\n" +
+      lines.map((line, i) => `${i === 0 ? "" : "T*\n"}(${escape(line)}) Tj\n`).join("") +
+      "ET";
+
+    const objects = [
+      "<< /Type /Catalog /Pages 2 0 R >>",
+      "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+      "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
+      "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+      `<< /Length ${Buffer.byteLength(stream, "latin1")} >>\nstream\n${stream}\nendstream`,
+    ];
+
+    let pdf = "%PDF-1.4\n";
+    const offsets: number[] = [];
+    objects.forEach((object, index) => {
+      offsets.push(Buffer.byteLength(pdf, "latin1"));
+      pdf += `${index + 1} 0 obj\n${object}\nendobj\n`;
+    });
+    while (Buffer.byteLength(pdf, "latin1") < MIN_VALID_PDF_BYTES) pdf += "% pad\n";
+    const xrefOffset = Buffer.byteLength(pdf, "latin1");
+    pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+    for (const offset of offsets) pdf += `${String(offset).padStart(10, "0")} 00000 n \n`;
+    pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`;
+    return Buffer.from(pdf, "latin1");
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice-numbering.util.ts b/apps/edr-freight-api/src/modules/billing/invoice-numbering.util.ts
new file mode 100644
index 000000000..d36788600
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice-numbering.util.ts
@@ -0,0 +1,44 @@
+/**
+ * Shared per-day sequential invoice numbering, used by every billing source
+ * (freight `FRT-…`, warehouse fees `WHF-…`, …) so the format and the
+ * `MAX(seq)+1` allocation live in one place instead of being copy-pasted per
+ * service.
+ *
+ * Produces `<CODE>-YYYYMMDD-00001`: the sequence is the max existing suffix for
+ * the day + 1. Run inside the caller's transaction (pass that transaction's
+ * manager) so concurrent generation within a transaction stays consistent.
+ */
+
+/** Anything exposing TypeORM's `.query` — an `EntityManager` or `DataSource`. */
+export interface SqlRunner {
+  query(sql: string, params?: unknown[]): Promise<Array<{ seq: number | string }>>;
+}
+
+export interface InvoiceNumberOptions {
+  /** Schema-qualified table to scan, e.g. `freight.invoices`. */
+  table: string;
+  /** Document code prefix, e.g. `FRT` or `WHF`. */
+  code: string;
+  /** Column holding the number; defaults to `invoice_number`. */
+  column?: string;
+  /** Clock injection point (tests); defaults to now. */
+  now?: Date;
+}
+
+export async function nextDailyInvoiceNumber(
+  runner: SqlRunner,
+  opts: InvoiceNumberOptions,
+): Promise<string> {
+  const now = opts.now ?? new Date();
+  const ymd = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, "0")}${String(now.getDate()).padStart(2, "0")}`;
+  const prefix = `${opts.code}-${ymd}-`;
+  const column = opts.column ?? "invoice_number";
+
+  const [row] = await runner.query(
+    `SELECT COALESCE(MAX(CAST(split_part(${column}, '-', 3) AS int)), 0) AS seq
+       FROM ${opts.table} WHERE ${column} LIKE $1`,
+    [`${prefix}%`],
+  );
+  const next = Number(row?.seq ?? 0) + 1;
+  return `${prefix}${String(next).padStart(5, "0")}`;
+}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts b/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts
new file mode 100644
index 000000000..ab1e27b1a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts
@@ -0,0 +1,36 @@
+/**
+ * Shared payment/settlement math for invoices. Both the global
+ * `BillingService.recordPayment` and the warehouse fee invoice flow apply a
+ * payment the same way — accumulate `paidAmount`, derive the outstanding
+ * `balanceAmount`, and decide whether the invoice is now fully settled. Keeping
+ * it here means the two flows can never drift on rounding or the
+ * partial-vs-full threshold.
+ */
+
+/** Round to 2 decimals, avoiding binary float drift. */
+export const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+export interface SettlementResult {
+  /** New cumulative amount paid. */
+  paidAmount: number;
+  /** Remaining balance (0 once fully paid). */
+  balanceAmount: number;
+  /** True once the balance reaches zero. */
+  fullyPaid: boolean;
+}
+
+/**
+ * Apply a single payment of `amount` to an invoice with `totalAmount` already
+ * carrying `currentPaid`. Caller is responsible for validating `amount > 0` and
+ * the invoice being in a payable state.
+ */
+export function applySettlement(
+  totalAmount: number,
+  currentPaid: number,
+  amount: number,
+): SettlementResult {
+  const total = Number(totalAmount);
+  const paidAmount = round2(Number(currentPaid) + Number(amount));
+  const balanceAmount = Math.max(0, round2(total - paidAmount));
+  return { paidAmount, balanceAmount, fullyPaid: paidAmount >= total };
+}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
index 1fe184662..904728251 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
@@ -1,6 +1,12 @@
 import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { DataSource } from 'typeorm';
 
+import {
+  InvoiceDocumentModel,
+  InvoiceDocumentService,
+} from '../billing/documents/invoice-document.service';
+import { nextDailyInvoiceNumber } from '../billing/invoice-numbering.util';
+import { applySettlement } from '../billing/invoice-settlement.util';
 import { NotificationsService } from '../notifications/notifications.service';
 import {
   WarehouseFeeInvoice,
@@ -11,7 +17,6 @@ import { WarehouseFeeType } from './entities/warehouse-fee-invoice-item.entity';
 import { WarehouseFeeInvoiceItemRepository } from './warehouse-fee-invoice-item.repository';
 import { WarehouseFeeInvoiceRepository } from './warehouse-fee-invoice.repository';
 import { WarehouseFeeService } from './warehouse-fee.service';
-import { WarehouseReleaseDocumentService } from './warehouse-release-document.service';
 
 interface GenerateOptions {
   confirmZero?: boolean;
@@ -56,7 +61,7 @@ export class WarehouseInvoiceService {
     private readonly invoiceRepository: WarehouseFeeInvoiceRepository,
     private readonly itemRepository: WarehouseFeeInvoiceItemRepository,
     private readonly feeService: WarehouseFeeService,
-    private readonly documents: WarehouseReleaseDocumentService,
+    private readonly invoiceDocuments: InvoiceDocumentService,
     private readonly notifications: NotificationsService,
   ) {}
 
@@ -161,18 +166,12 @@ export class WarehouseInvoiceService {
     return saved;
   }
 
-  /** WHF-YYYYMMDD-00001 — sequential per day. */
-  private async nextInvoiceNumber(): Promise<string> {
-    const now = new Date();
-    const ymd = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`;
-    const prefix = `WHF-${ymd}-`;
-    const [row] = await this.dataSource.query(
-      `SELECT COALESCE(MAX(CAST(split_part(invoice_number, '-', 3) AS int)), 0) AS seq
-         FROM freight.warehouse_fee_invoices WHERE invoice_number LIKE $1`,
-      [`${prefix}%`],
-    );
-    const next = Number(row?.seq ?? 0) + 1;
-    return `${prefix}${String(next).padStart(5, '0')}`;
+  /** WHF-YYYYMMDD-00001 — sequential per day (shared billing numbering). */
+  private nextInvoiceNumber(): Promise<string> {
+    return nextDailyInvoiceNumber(this.dataSource, {
+      table: 'freight.warehouse_fee_invoices',
+      code: 'WHF',
+    });
   }
 
   // ── Reads ────────────────────────────────────────────────────────────────
@@ -186,12 +185,7 @@ export class WarehouseInvoiceService {
 
   async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
     const invoice = await this.findById(id);
-    const details = await this.getInvoiceDocumentDetails(invoice);
-    const html = this.buildInvoiceDocumentHtml(invoice, 'INVOICE', details);
-    return {
-      filename: `warehouse-invoice-${this.safeFilename(invoice.invoiceNumber)}.pdf`,
-      buffer: await this.documents.htmlToPdfBuffer(html),
-    };
+    return this.invoiceDocuments.render(this.toDocumentModel(invoice, 'INVOICE'));
   }
 
   async receipt(id: string): Promise<{ filename: string; buffer: Buffer }> {
@@ -199,11 +193,69 @@ export class WarehouseInvoiceService {
     if (Number(invoice.paidAmount) <= 0) {
       throw new BadRequestException('A receipt is available only after payment is recorded.');
     }
-    const details = await this.getInvoiceDocumentDetails(invoice);
-    const html = this.buildInvoiceDocumentHtml(invoice, 'RECEIPT', details);
+    return this.invoiceDocuments.render(this.toDocumentModel(invoice, 'RECEIPT'));
+  }
+
+  /** Map a warehouse fee invoice (with display details + items) onto the shared document model. */
+  private toDocumentModel(
+    invoice: WarehouseFeeInvoiceWithDisplay & { items: unknown[] },
+    kind: 'INVOICE' | 'RECEIPT',
+  ): InvoiceDocumentModel {
+    const items = invoice.items as Array<{
+      description?: string;
+      feeType?: string;
+      quantity?: number;
+      unitRate?: number;
+      amount?: number;
+      currency?: string;
+      chargeableDays?: number | null;
+    }>;
+    const lastPayment = [...(invoice.payments ?? [])].pop();
+    const date = (value: unknown) =>
+      value ? new Date(value as string | Date).toLocaleDateString('en-GB') : null;
+
     return {
-      filename: `warehouse-receipt-${this.safeFilename(invoice.invoiceNumber)}.pdf`,
-      buffer: await this.documents.htmlToPdfBuffer(html),
+      kind,
+      title: 'Warehouse Fee',
+      documentNumber: invoice.invoiceNumber,
+      issuedAt: invoice.issuedAt ?? invoice.createdAt,
+      status: invoice.status,
+      currency: invoice.currency,
+      summary: [
+        { label: 'Status', value: invoice.status.replace(/_/g, ' ') },
+        { label: 'Invoice type', value: invoice.invoiceType.replace(/_/g, ' ') },
+        { label: 'Booking reference', value: invoice.bookingReference ?? null },
+        { label: 'Customer', value: invoice.customerName ?? null },
+        { label: 'Inventory reference', value: invoice.inventoryReference ?? null },
+        { label: 'Inventory info', value: invoice.inventoryInfo ?? null },
+        { label: 'Clearance', value: invoice.clearanceStatus ?? null },
+        { label: 'Warehouse', value: invoice.warehouseName ?? null },
+        {
+          label: 'Yard / Zone',
+          value: [invoice.yardName, invoice.zoneName].filter(Boolean).join(' / ') || null,
+        },
+        { label: 'Period', value: `${date(invoice.periodStart) ?? '-'} - ${date(invoice.periodEnd) ?? '-'}` },
+        {
+          label: 'Payment',
+          value: lastPayment ? `${lastPayment.method ?? 'MANUAL'} / ${date(lastPayment.paidAt) ?? '-'}` : null,
+        },
+      ],
+      categoryHeader: 'Fee type',
+      lines: items.map((item) => ({
+        description: item.description ?? null,
+        category: item.feeType ?? null,
+        quantity: item.quantity ?? item.chargeableDays ?? 0,
+        unitRate: item.unitRate,
+        amount: item.amount,
+        currency: item.currency ?? invoice.currency,
+      })),
+      totals: [
+        { label: 'Subtotal', amount: Number(invoice.subtotalAmount) },
+        { label: 'Tax', amount: Number(invoice.taxAmount) },
+        { label: 'Total', amount: Number(invoice.totalAmount), grand: true },
+        { label: 'Paid', amount: Number(invoice.paidAmount) },
+        { label: 'Balance', amount: Number(invoice.balanceAmount) },
+      ],
     };
   }
 
@@ -237,10 +289,11 @@ export class WarehouseInvoiceService {
     if (invoice.status === 'PAID') throw new BadRequestException('Invoice is already fully paid.');
     if (!(dto.amount > 0)) throw new BadRequestException('Payment amount must be greater than zero.');
 
-    const paidAmount = Number(invoice.paidAmount) + dto.amount;
-    const total = Number(invoice.totalAmount);
-    const balance = Math.max(0, Math.round((total - paidAmount) * 100) / 100);
-    const fullyPaid = paidAmount >= total;
+    const { paidAmount, balanceAmount, fullyPaid } = applySettlement(
+      invoice.totalAmount,
+      invoice.paidAmount,
+      dto.amount,
+    );
 
     const payments = [
       ...(invoice.payments ?? []),
@@ -248,8 +301,8 @@ export class WarehouseInvoiceService {
     ];
 
     const updated = await this.invoiceRepository.update(id, {
-      paidAmount: Math.round(paidAmount * 100) / 100,
-      balanceAmount: balance,
+      paidAmount,
+      balanceAmount,
       status: fullyPaid ? 'PAID' : 'PARTIALLY_PAID',
       paidAt: fullyPaid ? new Date() : invoice.paidAt ?? null,
       payments,
@@ -460,131 +513,4 @@ export class WarehouseInvoiceService {
 
     await this.sendSms(driverPhone, driverMessage, `warehouse pickup driver ${invoice.invoiceNumber}`);
   }
-
-  private buildInvoiceDocumentHtml(
-    invoice: WarehouseFeeInvoiceWithDisplay & { items: unknown[] },
-    kind: 'INVOICE' | 'RECEIPT',
-    details: InvoiceDocumentDetails,
-  ): string {
-    const esc = (value: unknown) =>
-      String(value ?? '-')
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-    const money = (amount: unknown, currency = invoice.currency) =>
-      `${Number(amount ?? 0).toLocaleString()} ${currency === 'ETB' ? 'Birr (ETB)' : currency}`;
-    const date = (value: unknown) => (value ? new Date(value as string | Date).toLocaleDateString('en-GB') : '-');
-    const items = invoice.items as Array<{
-      id?: string;
-      description?: string;
-      feeType?: string;
-      quantity?: number;
-      unitRate?: number;
-      amount?: number;
-      currency?: string;
-      chargeableDays?: number | null;
-    }>;
-    const lastPayment = [...(invoice.payments ?? [])].pop();
-    const sealText = kind === 'RECEIPT' || invoice.status === 'PAID' ? 'EDR PAID' : 'EDR';
-
-    return `<!doctype html>
-<html>
-<head>
-  <meta charset="utf-8" />
-  <title>Warehouse Fee ${kind === 'RECEIPT' ? 'Receipt' : 'Invoice'}</title>
-  <style>
-    body { font-family: Arial, sans-serif; color: #0f172a; margin: 0; }
-    .doc { padding: 16px 8px; position: relative; }
-    .top { display: flex; justify-content: space-between; gap: 24px; border-bottom: 3px solid #0f766e; padding-bottom: 16px; }
-    .brand { font-size: 13px; color: #475569; text-transform: uppercase; letter-spacing: .08em; }
-    h1 { margin: 8px 0 0; font-size: 30px; }
-    .meta { text-align: right; font-size: 12px; color: #475569; }
-    .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
-    .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
-    .summary { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 28px; margin: 24px 150px 16px 0; font-size: 13px; }
-    .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; }
-    .summary span { color: #64748b; display: block; font-size: 11px; margin-bottom: 3px; }
-    table { width: 100%; border-collapse: collapse; margin-top: 18px; }
-    th { text-align: left; background: #f8fafc; color: #475569; }
-    th, td { border: 1px solid #cbd5e1; padding: 9px 10px; font-size: 12px; }
-    td.num, th.num { text-align: right; }
-    .totals { margin-left: auto; width: 330px; margin-top: 18px; }
-    .total-row { display: flex; justify-content: space-between; border-bottom: 1px solid #e2e8f0; padding: 8px 0; font-size: 13px; }
-    .grand { font-size: 16px; font-weight: 800; }
-    .footer { margin-top: 34px; display: grid; grid-template-columns: 1fr 1fr; gap: 28px; }
-    .line { border-top: 1px solid #334155; padding-top: 8px; font-size: 12px; color: #475569; }
-  </style>
-</head>
-<body>
-  <div class="doc">
-    <div class="top">
-      <div>
-        <div class="brand">Ethio-Djibouti Railway S.C.</div>
-        <h1>Warehouse Fee ${kind === 'RECEIPT' ? 'Receipt' : 'Invoice'}</h1>
-      </div>
-      <div class="meta">
-        Document no.
-        <strong>${esc(invoice.invoiceNumber)}</strong>
-        Issued: ${esc(date(invoice.issuedAt ?? invoice.createdAt))}
-      </div>
-    </div>
-    <div class="seal">${esc(sealText)}</div>
-    <div class="summary">
-      <div><span>Status</span>${esc(invoice.status.replace(/_/g, ' '))}</div>
-      <div><span>Invoice type</span>${esc(invoice.invoiceType.replace(/_/g, ' '))}</div>
-      <div><span>Booking reference</span>${esc(details.bookingReference)}</div>
-      <div><span>Customer</span>${esc(details.customerName)}</div>
-      <div><span>Inventory reference</span>${esc(details.inventoryReference)}</div>
-      <div><span>Inventory info</span>${esc(details.inventoryInfo)}</div>
-      <div><span>Clearance</span>${esc(details.clearanceStatus)}</div>
-      <div><span>Warehouse</span>${esc(details.warehouseName)}</div>
-      <div><span>Yard / Zone</span>${esc([details.yardName, details.zoneName].filter(Boolean).join(' / ') || null)}</div>
-      <div><span>Period</span>${esc(date(invoice.periodStart))} - ${esc(date(invoice.periodEnd))}</div>
-      <div><span>Payment</span>${esc(lastPayment ? `${lastPayment.method ?? 'MANUAL'} / ${date(lastPayment.paidAt)}` : '-')}</div>
-    </div>
-    <table>
-      <thead>
-        <tr>
-          <th>Description</th>
-          <th>Fee type</th>
-          <th class="num">Qty</th>
-          <th class="num">Rate</th>
-          <th class="num">Amount</th>
-        </tr>
-      </thead>
-      <tbody>
-        ${items
-          .map(
-            (item) => `<tr>
-              <td>${esc(item.description)}</td>
-              <td>${esc((item.feeType ?? '').replace(/_/g, ' '))}</td>
-              <td class="num">${esc(item.quantity ?? item.chargeableDays ?? 0)}</td>
-              <td class="num">${esc(money(item.unitRate, item.currency ?? invoice.currency))}</td>
-              <td class="num">${esc(money(item.amount, item.currency ?? invoice.currency))}</td>
-            </tr>`,
-          )
-          .join('')}
-      </tbody>
-    </table>
-    <div class="totals">
-      <div class="total-row"><span>Subtotal</span><strong>${esc(money(invoice.subtotalAmount))}</strong></div>
-      <div class="total-row"><span>Tax</span><strong>${esc(money(invoice.taxAmount))}</strong></div>
-      <div class="total-row grand"><span>Total</span><strong>${esc(money(invoice.totalAmount))}</strong></div>
-      <div class="total-row"><span>Paid</span><strong>${esc(money(invoice.paidAmount))}</strong></div>
-      <div class="total-row"><span>Balance</span><strong>${esc(money(invoice.balanceAmount))}</strong></div>
-    </div>
-    <div class="footer">
-      <div class="line">Prepared by EDR warehouse finance</div>
-      <div class="line">Authorized seal / signature</div>
-    </div>
-  </div>
-</body>
-</html>`;
-  }
-
-  private safeFilename(value: string): string {
-    return value.replace(/[^a-zA-Z0-9_-]+/g, '-');
-  }
 }
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-release-document.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-release-document.service.ts
index a77a46c29..f8c0dd355 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-release-document.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-release-document.service.ts
@@ -1,101 +1,23 @@
-import { existsSync } from 'fs';
+import { Injectable } from '@nestjs/common';
 
-import { Injectable, InternalServerErrorException, Logger } from '@nestjs/common';
+import { PdfRenderService } from '../billing/documents/pdf-render.service';
 
 const MIN_VALID_PDF_BYTES = 2_000;
 
-const RELEASE_DOCUMENT_PRINT_STYLES = `
-<style id="warehouse-release-document-print-fix">
-  @media print {
-    html, body {
-      background: #fff !important;
-      -webkit-print-color-adjust: exact;
-      print-color-adjust: exact;
-    }
-  }
-</style>`;
-
 @Injectable()
 export class WarehouseReleaseDocumentService {
-  private readonly logger = new Logger(WarehouseReleaseDocumentService.name);
+  constructor(private readonly pdf: PdfRenderService) {}
 
-  async htmlToPdfBuffer(html: string): Promise<Buffer> {
-    const preparedHtml = this.injectPdfPrintStyles(html);
-    const executablePath = this.resolveExecutablePath();
-
-    try {
-      const puppeteer = await import('puppeteer');
-      const launchOptions: import('puppeteer').LaunchOptions = {
-        headless: true,
-        args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-        ...(executablePath ? { executablePath } : {}),
-      };
-
-      const browser = await puppeteer.default.launch(launchOptions);
-      try {
-        const page = await browser.newPage();
-        await page.setViewport({ width: 794, height: 1123, deviceScaleFactor: 1 });
-        await page.setContent(preparedHtml, { waitUntil: 'load', timeout: 60_000 });
-        await page.emulateMediaType('print');
-        await new Promise((resolve) => setTimeout(resolve, 250));
-
-        const pdf = await page.pdf({
-          format: 'A4',
-          printBackground: true,
-          margin: { top: '16mm', bottom: '18mm', left: '14mm', right: '14mm' },
-        });
-
-        const buffer = Buffer.from(pdf);
-        if (!this.isValidPdf(buffer)) {
-          throw new Error(`Puppeteer produced invalid release PDF (${buffer.length} bytes)`);
-        }
-        this.logger.log(
-          `Warehouse release PDF rendered (${buffer.length} bytes) via ${executablePath ?? 'bundled Chromium'}`,
-        );
-        return buffer;
-      } finally {
-        await browser.close();
-      }
-    } catch (error) {
-      this.logger.error(
-        `Warehouse release PDF failed (executable=${executablePath ?? 'default'}): ${error}`,
-      );
-      const fallback = this.htmlToBasicPdfBuffer(preparedHtml);
-      if (this.isValidPdf(fallback)) {
-        this.logger.warn(
-          `Using basic warehouse release PDF fallback (${fallback.length} bytes). Install Chromium or set PUPPETEER_EXECUTABLE_PATH for full layout rendering.`,
-        );
-        return fallback;
-      }
-      throw new InternalServerErrorException(
-        'Warehouse release PDF could not be generated. Ensure Chromium is installed or set PUPPETEER_EXECUTABLE_PATH.',
-      );
-    }
-  }
-
-  private injectPdfPrintStyles(html: string): string {
-    if (html.includes('warehouse-release-document-print-fix')) return html;
-    if (html.includes('</head>')) {
-      return html.replace('</head>', `${RELEASE_DOCUMENT_PRINT_STYLES}</head>`);
-    }
-    return `${RELEASE_DOCUMENT_PRINT_STYLES}${html}`;
-  }
-
-  private resolveExecutablePath(): string | undefined {
-    const fromEnv = process.env.PUPPETEER_EXECUTABLE_PATH?.trim();
-    if (fromEnv && existsSync(fromEnv)) return fromEnv;
-
-    const candidates = [
-      '/usr/bin/chromium',
-      '/usr/bin/chromium-browser',
-      '/usr/bin/google-chrome-stable',
-      '/usr/bin/google-chrome',
-    ];
-    return candidates.find((path) => existsSync(path));
-  }
-
-  private isValidPdf(buffer: Buffer): boolean {
-    return buffer.length >= MIN_VALID_PDF_BYTES && buffer.subarray(0, 5).toString('ascii') === '%PDF-';
+  /**
+   * Render the gate-clearance release document to PDF via the shared renderer,
+   * falling back to the release-specific hand-built layout when Chromium is
+   * unavailable.
+   */
+  htmlToPdfBuffer(html: string): Promise<Buffer> {
+    return this.pdf.htmlToPdfBuffer(html, {
+      label: 'Warehouse release',
+      fallback: (preparedHtml) => this.htmlToBasicPdfBuffer(preparedHtml),
+    });
   }
 
   private htmlToBasicPdfBuffer(html: string): Buffer {
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts b/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
index d880a3554..a7ce68319 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
@@ -3,6 +3,7 @@ import { ConfigService } from '@nestjs/config';
 import { ExchangeModule, ExchangeOptions } from '@edr/api-common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { DocumentsModule } from '../billing/documents/documents.module';
 import { FilesModule } from '../files/files.module';
 import { InterchangeDocumentsModule } from '../interchange-documents/interchange-documents.module';
 import { LastMileModule } from '../last-mile/last-mile.module';
@@ -70,6 +71,7 @@ import { WarehousesService } from './warehouses.service';
       WarehouseFeeInvoice,
       WarehouseFeeInvoiceItem,
     ]),
+    DocumentsModule,
     FilesModule,
     InterchangeDocumentsModule,
     forwardRef(() => LastMileModule),

From 2bbb37207e5313a67006407d19db962a9936a1c8 Mon Sep 17 00:00:00 2001
From: yonastewabe <yonastewabe21@gmail.com>
Date: Tue, 30 Jun 2026 15:16:47 +0300
Subject: [PATCH 54/63] feat: implement automated environment synchronization
 and conditional CI/CD deployment workflows

---
 .github/workflows/deploy.yml                  |  2 +-
 docker-compose.yaml                           | 24 +++---
 infrastructure/docker/Dockerfile.web          |  4 -
 .../deploy/sync-env-from-server-jenkins.sh    | 74 +++++++++++++++++++
 scripts/deploy/sync-env-from-server.sh        | 25 +------
 5 files changed, 90 insertions(+), 39 deletions(-)
 create mode 100644 scripts/deploy/sync-env-from-server-jenkins.sh

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 78c15cba1..fcd560a95 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -50,7 +50,7 @@ jobs:
 
           SERVICES=()
 
-          NON_DEPLOYABLE_PATTERN="^docs/|^README[.]md$|^DEPLOYMENT[.]md$|^CLAUDE[.]md$|^checkpoint[.]md$|^orgstructure[.]md$|^ITMLS_DB_Design[.]md$|.*[.]md$|^[.]eslintrc|^[.]prettierrc|^[.]editorconfig|^[.]gitignore|^[.]gitattributes|^commitlint[.]config[.]js$"
+          NON_DEPLOYABLE_PATTERN="^docs/|^README[.]md$|^DEPLOYMENT[.]md$|^CLAUDE[.]md$|^checkpoint[.]md$|^orgstructure[.]md$|^ITMLS_DB_Design[.]md$|.*[.]md$|^[.]eslintrc|^[.]prettierrc|^[.]editorconfig|^[.]gitignore|^[.]gitattributes|^commitlint[.]config[.]js$|^scripts/deploy/sync-env-from-server-jenkins[.]sh$"
 
           GLOBAL_PATTERN="^[.]github/|^docker-compose[.]yaml$|^turbo[.]json$|^tsconfig[.]json$|^tsconfig[.]base[.]json$|^pnpm-workspace[.]yaml$|^pnpm-lock[.]yaml$|^package[.]json$|^[.]env([.][a-z]+)?$|^packages/|^local-packages/|^infrastructure/|^scripts/deploy/|^wagon[.][^/]*[.]ts$|^cargo[.][^/]*[.]ts$|^container[.][^/]*[.]ts$|^use-[^/]*[.]ts$|^[^/]*[.]service[.]ts$|^[^/]*[.]entity[.]ts$|^[^/]*-types[.]ts$"
 
diff --git a/docker-compose.yaml b/docker-compose.yaml
index a045125bb..5ea74843b 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -39,14 +39,14 @@ services:
       args:
         TURBO_FILTER: "@edr/freight-portal"
         APP_PATH: apps/edr-freight-web/portal
-        VITE_API_URL: ${VITE_API_URL:-https://edrfreightapi.triaplc.com/api}
-        VITE_BASE_API_URL: ${VITE_BASE_API_URL:-https://edrfreightapi.triaplc.com}
-        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:-/_um}
+        VITE_API_URL: ${VITE_API_URL:?VITE_API_URL must be set}
+        VITE_BASE_API_URL: ${VITE_BASE_API_URL:?VITE_BASE_API_URL must be set}
+        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:?VITE_USER_MANAGEMENT_BASE must be set}
       secrets:
         - npmrc
     ports:
       - "${FREIGHT_PORTAL_PORT:-5173}:80"
-  
+
   freight-backoffice:
     build:
       context: .
@@ -54,14 +54,14 @@ services:
       args:
         TURBO_FILTER: "@edr/freight-backoffice"
         APP_PATH: apps/edr-freight-web/backoffice
-        VITE_API_URL: ${VITE_API_URL:-https://edrfreightapi.triaplc.com/api}
-        VITE_BASE_API_URL: ${VITE_BASE_API_URL:-https://edrfreightapi.triaplc.com}
-        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:-/_um}
+        VITE_API_URL: ${VITE_API_URL:?VITE_API_URL must be set}
+        VITE_BASE_API_URL: ${VITE_BASE_API_URL:?VITE_BASE_API_URL must be set}
+        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:?VITE_USER_MANAGEMENT_BASE must be set}
       secrets:
         - npmrc
     ports:
       - "${FREIGHT_BACKOFFICE_PORT:-5183}:80"
-  
+
   passenger-portal:
     build:
       context: .
@@ -69,14 +69,14 @@ services:
       args:
         APP_PACKAGE: "@edr/passenger-portal"
         APP_PATH: apps/edr-passenger-web/portal
-        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:4000}
+        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:?NEXT_PUBLIC_API_URL must be set}
       secrets:
         - npmrc
     ports:
       - "${PASSENGER_PORTAL_PORT:-5174}:${PASSENGER_PORTAL_PORT:-5174}"
     env_file:
       - apps/edr-passenger-web/portal/.env
-  
+
   passenger-backoffice:
     build:
       context: .
@@ -84,14 +84,14 @@ services:
       args:
         APP_PACKAGE: "@edr/passenger-backoffice"
         APP_PATH: apps/edr-passenger-web/backoffice
-        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:4000}
+        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:?NEXT_PUBLIC_API_URL must be set}
       secrets:
         - npmrc
     ports:
       - "${PASSENGER_BACKOFFICE_PORT:-5184}:${PASSENGER_BACKOFFICE_PORT:-5184}"
     env_file:
       - apps/edr-passenger-web/backoffice/.env
-
+  
   payment-api:
     build:
       context: .
diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index 1ccdeb81f..65c26a694 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -2,10 +2,6 @@
 
 ARG TURBO_FILTER=@edr/freight-portal
 ARG APP_PATH=apps/edr-freight-web/portal
-ARG VITE_API_URL=https://edrfreightapi.triaplc.com/api
-ARG VITE_BASE_API_URL=https://edrfreightapi.triaplc.com
-ARG VITE_USER_MANAGEMENT_BASE=/_um
-ARG NEXT_PUBLIC_API_URL=http://localhost:4000
 
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
diff --git a/scripts/deploy/sync-env-from-server-jenkins.sh b/scripts/deploy/sync-env-from-server-jenkins.sh
new file mode 100644
index 000000000..74b9a3f13
--- /dev/null
+++ b/scripts/deploy/sync-env-from-server-jenkins.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Sync .env files from the self-hosted runner filesystem into the repo.
+# Jenkins variant — exports variables as KEY=VALUE lines into $CI_ENV_FILE,
+# which the Jenkinsfile loads with readProperties + withEnv. Jenkins has no
+# equivalent of GitHub Actions' $GITHUB_ENV, and each `sh` step runs in its
+# own process, so this file is the hand-off point between stages.
+#
+# Usage:
+#   PROJECT=edr-freight BRANCH=main CI_ENV_FILE=/tmp/passenger-api.env \
+#     ./scripts/deploy/sync-env-from-server-jenkins.sh passenger-api
+#
+# Server layout (one file per service):
+#   /home/user/environmen/<project>/<branch-slug>/freight-api.env
+#   /home/user/environmen/<project>/<branch-slug>/freight-portal.env
+
+set -euo pipefail
+
+DEPLOY_USER="${DEPLOY_USER:-tria}"
+BRANCH="${BRANCH:?BRANCH is required}"
+BRANCH_SLUG="${BRANCH_SLUG:-$(echo "${BRANCH}" | tr "[:upper:]" "[:lower:]" | sed -E "s/[^a-z0-9]+/-/g; s/^-+//; s/-+$//")}"
+ENV_ROOT="${ENV_ROOT:-/home/${DEPLOY_USER}/environment/edr/${BRANCH_SLUG}/${PROJECT:?PROJECT is required}}"
+CI_ENV_FILE="${CI_ENV_FILE:?CI_ENV_FILE is required (e.g. \${WORKSPACE}/.ci-env/<service>.env)}"
+
+if [[ ! -d "${ENV_ROOT}" ]]; then
+  echo "Environment directory not found: ${ENV_ROOT}" >&2
+  exit 1
+fi
+echo "Using environment directory: ${ENV_ROOT}"
+
+mkdir -p "$(dirname "${CI_ENV_FILE}")"
+: > "${CI_ENV_FILE}"
+
+declare -A SERVICE_ENV_TARGET=(
+  ["freight-api"]="apps/edr-freight-api/.env"
+  ["freight-portal"]="apps/edr-freight-web/portal/.env"
+  ["freight-backoffice"]="apps/edr-freight-web/backoffice/.env"
+  ["passenger-api"]="apps/edr-passenger-api/.env"
+  ["passenger-portal"]="apps/edr-passenger-web/portal/.env"
+  ["passenger-backoffice"]="apps/edr-passenger-web/backoffice/.env"
+  ["payment-api"]="apps/edr-payment-api/.env"
+)
+
+for service in "$@"; do
+  src="${ENV_ROOT}/${service}.env"
+  dest="${SERVICE_ENV_TARGET[${service}]:-}"
+
+  if [[ -z "${dest}" ]]; then
+    echo "Unknown service: ${service}" >&2
+    exit 1
+  fi
+
+  if [[ ! -f "${src}" ]]; then
+    echo "Missing env file: ${src}" >&2
+    exit 1
+  fi
+
+  mkdir -p "$(dirname "${dest}")"
+  cp "${src}" "${dest}"
+  echo "Synced ${src} -> ${dest}"
+
+  port_value=$(sed -n -E 's/^[[:space:]]*PORT[[:space:]]*=[[:space:]]*"?([^"#]+)"?[[:space:]]*(#.*)?$/\1/p' "${src}" | head -n1 | tr -d '[:space:]')
+  if [[ -z "${port_value}" ]]; then
+    echo "Missing required PORT in env file: ${src}" >&2
+    exit 1
+  fi
+
+  service_var=$(echo "${service}" | tr '[:lower:]-' '[:upper:]_')
+  echo "${service_var}_PORT=${port_value}" >> "${CI_ENV_FILE}"
+  echo "Exported ${service_var}_PORT from ${src}"
+
+  # Forward NEXT_PUBLIC_* and VITE_* vars so docker compose build can inject them as build args.
+  grep -E '^[[:space:]]*(NEXT_PUBLIC_|VITE_)[A-Za-z0-9_]+=' "${src}" \
+    | sed -E 's/^[[:space:]]*//' >> "${CI_ENV_FILE}" || true
+done
\ No newline at end of file
diff --git a/scripts/deploy/sync-env-from-server.sh b/scripts/deploy/sync-env-from-server.sh
index 795ab25b2..025c518b5 100644
--- a/scripts/deploy/sync-env-from-server.sh
+++ b/scripts/deploy/sync-env-from-server.sh
@@ -7,7 +7,6 @@
 # Server layout (one file per service):
 #   /home/user/environmen/<project>/<branch-slug>/freight-api.env
 #   /home/user/environmen/<project>/<branch-slug>/freight-portal.env
-#   /home/user/environmen/<project>/<branch-slug>/freight-web.build.env  (optional, exports VITE_API_URL etc.)
 
 set -euo pipefail
 
@@ -62,26 +61,8 @@ for service in "$@"; do
     echo "${service_var}_PORT=${port_value}" >> "${GITHUB_ENV}"
     echo "Exported ${service_var}_PORT from ${src}"
 
-    # Forward NEXT_PUBLIC_* vars so docker compose build can inject them as build args.
-    grep -E '^[[:space:]]*NEXT_PUBLIC_[A-Za-z0-9_]+=' "${src}" \
+    # Forward NEXT_PUBLIC_* and VITE_* vars so docker compose build can inject them as build args.
+    grep -E '^[[:space:]]*(NEXT_PUBLIC_|VITE_)[A-Za-z0-9_]+=' "${src}" \
       | sed -E 's/^[[:space:]]*//' >> "${GITHUB_ENV}" || true
   fi
-done
-
-# Optional build-time variables (VITE_API_URL, etc.)
-# Set BUILD_ENV_FILE=freight-web.build.env or passenger-web.build.env per workflow.
-build_env_file="${BUILD_ENV_FILE:-web.build.env}"
-build_env="${ENV_ROOT}/${build_env_file}"
-if [[ -f "${build_env}" ]]; then
-  echo "Loading build variables from ${build_env}"
-  set -a
-  # shellcheck disable=SC1090
-  source "${build_env}"
-  set +a
-
-  if [[ -n "${GITHUB_ENV:-}" ]]; then
-    grep -E '^[[:space:]]*(export[[:space:]]+)?[A-Za-z_][A-Za-z0-9_]*=' "${build_env}" \
-      | sed -E 's/^[[:space:]]*export[[:space:]]+//' >> "${GITHUB_ENV}"
-    echo "Wrote build variables to GITHUB_ENV"
-  fi
-fi
+done
\ No newline at end of file

From 18e18bd15e0a1354b31c9f69c1123e8cbacf54d6 Mon Sep 17 00:00:00 2001
From: Yonas Tewabe <yonastewabe21@gmail.com>
Date: Tue, 30 Jun 2026 15:24:09 +0300
Subject: [PATCH 55/63] Update Dockerfile.web

---
 infrastructure/docker/Dockerfile.web | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index fc5e9ab7e..d5f77061e 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -5,10 +5,6 @@ ARG APP_PATH=apps/edr-freight-web/portal
 
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
-# Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
-# `--mount=type=cache,target=/pnpm/store` cache actually persists deps across builds.
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
 
@@ -35,6 +31,12 @@ ENV VITE_API_URL=${VITE_API_URL}
 ENV VITE_BASE_API_URL=${VITE_BASE_API_URL}
 ENV VITE_USER_MANAGEMENT_BASE=${VITE_USER_MANAGEMENT_BASE}
 ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
+
+RUN if [ -z "$VITE_API_URL" ] || [ -z "$VITE_BASE_API_URL" ] || [ -z "$VITE_USER_MANAGEMENT_BASE" ]; then \
+      echo "ERROR: VITE_API_URL, VITE_BASE_API_URL, and VITE_USER_MANAGEMENT_BASE must all be set" && \
+      exit 1; \
+    fi
+
 COPY --from=installer /app/ .
 COPY --from=pruner /app/out/full/ .
 

From 90f200fdc10b82ac4c445248fd5f8a98a0da271a Mon Sep 17 00:00:00 2001
From: Yonas Tewabe <yonastewabe21@gmail.com>
Date: Tue, 30 Jun 2026 15:26:23 +0300
Subject: [PATCH 56/63] Update Dockerfile.passenger-web

---
 infrastructure/docker/Dockerfile.passenger-web | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/infrastructure/docker/Dockerfile.passenger-web b/infrastructure/docker/Dockerfile.passenger-web
index 9d9adac08..61b58736b 100644
--- a/infrastructure/docker/Dockerfile.passenger-web
+++ b/infrastructure/docker/Dockerfile.passenger-web
@@ -10,12 +10,10 @@
 #     --build-arg PORT=5174 \
 #     -f infrastructure/docker/Dockerfile.passenger-web .
 #
-
 ARG APP_PACKAGE=@edr/passenger-portal
 ARG APP_PATH=apps/edr-passenger-web/portal
 ARG PORT=5174
 ARG NEXT_PUBLIC_API_URL
-
 FROM node:24.15.0-alpine AS base
 RUN apk add --no-cache libc6-compat
 # Store pnpm's content-addressable store under PNPM_HOME so the BuildKit
@@ -24,34 +22,35 @@ ENV PNPM_HOME="/pnpm"
 ENV PATH="$PNPM_HOME:$PATH"
 RUN corepack enable
 WORKDIR /app
-
 FROM base AS pruner
 ARG APP_PACKAGE
 COPY . .
 RUN pnpm dlx turbo prune "${APP_PACKAGE}" --docker
-
 FROM base AS installer
 COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
     --mount=type=cache,id=pnpm,target=/pnpm/store \
     pnpm install --frozen-lockfile
-
 FROM base AS builder
 ARG APP_PACKAGE
 ARG APP_PATH
 ARG NEXT_PUBLIC_API_URL
 ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
+
+RUN if [ -z "$NEXT_PUBLIC_API_URL" ]; then \
+      echo "ERROR: NEXT_PUBLIC_API_URL must be set" && \
+      exit 1; \
+    fi
+
 COPY --from=installer /app/ .
 COPY --from=pruner /app/out/full/ .
 RUN pnpm turbo build --filter="${APP_PACKAGE}..."
-
 FROM base AS deployer
 ARG APP_PACKAGE
 COPY --from=builder /app/ .
 RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
     pnpm deploy --filter="${APP_PACKAGE}" --prod --legacy /deploy
-
 FROM node:24.15.0-alpine AS runner
 ARG APP_PATH
 ARG PORT=5174

From 9f2f1b5138a910e1331b81037cb91de7d5da2ba7 Mon Sep 17 00:00:00 2001
From: Yonas Tewabe <yonastewabe21@gmail.com>
Date: Tue, 30 Jun 2026 15:28:39 +0300
Subject: [PATCH 57/63] Update docker-compose.yaml

---
 docker-compose.yaml | 22 ++++++++--------------
 1 file changed, 8 insertions(+), 14 deletions(-)

diff --git a/docker-compose.yaml b/docker-compose.yaml
index 5ea74843b..db3da060a 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -20,7 +20,6 @@ services:
       - apps/edr-freight-api/.env
     extra_hosts:
       - "paymentcallback.triaplc.com:10.18.7.179"
-
   passenger-api:
     build:
       context: .
@@ -31,7 +30,6 @@ services:
       - apps/edr-passenger-api/.env
     extra_hosts:
       - "paymentcallback.triaplc.com:10.18.7.179"
-
   freight-portal:
     build:
       context: .
@@ -39,14 +37,13 @@ services:
       args:
         TURBO_FILTER: "@edr/freight-portal"
         APP_PATH: apps/edr-freight-web/portal
-        VITE_API_URL: ${VITE_API_URL:?VITE_API_URL must be set}
-        VITE_BASE_API_URL: ${VITE_BASE_API_URL:?VITE_BASE_API_URL must be set}
-        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:?VITE_USER_MANAGEMENT_BASE must be set}
+        VITE_API_URL: ${VITE_API_URL:-}
+        VITE_BASE_API_URL: ${VITE_BASE_API_URL:-}
+        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:-}
       secrets:
         - npmrc
     ports:
       - "${FREIGHT_PORTAL_PORT:-5173}:80"
-
   freight-backoffice:
     build:
       context: .
@@ -54,14 +51,13 @@ services:
       args:
         TURBO_FILTER: "@edr/freight-backoffice"
         APP_PATH: apps/edr-freight-web/backoffice
-        VITE_API_URL: ${VITE_API_URL:?VITE_API_URL must be set}
-        VITE_BASE_API_URL: ${VITE_BASE_API_URL:?VITE_BASE_API_URL must be set}
-        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:?VITE_USER_MANAGEMENT_BASE must be set}
+        VITE_API_URL: ${VITE_API_URL:-}
+        VITE_BASE_API_URL: ${VITE_BASE_API_URL:-}
+        VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:-}
       secrets:
         - npmrc
     ports:
       - "${FREIGHT_BACKOFFICE_PORT:-5183}:80"
-
   passenger-portal:
     build:
       context: .
@@ -69,14 +65,13 @@ services:
       args:
         APP_PACKAGE: "@edr/passenger-portal"
         APP_PATH: apps/edr-passenger-web/portal
-        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:?NEXT_PUBLIC_API_URL must be set}
+        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-}
       secrets:
         - npmrc
     ports:
       - "${PASSENGER_PORTAL_PORT:-5174}:${PASSENGER_PORTAL_PORT:-5174}"
     env_file:
       - apps/edr-passenger-web/portal/.env
-
   passenger-backoffice:
     build:
       context: .
@@ -84,7 +79,7 @@ services:
       args:
         APP_PACKAGE: "@edr/passenger-backoffice"
         APP_PATH: apps/edr-passenger-web/backoffice
-        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:?NEXT_PUBLIC_API_URL must be set}
+        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-}
       secrets:
         - npmrc
     ports:
@@ -105,7 +100,6 @@ services:
       - "${PAYMENT_API_PORT:-3008}:${PAYMENT_API_PORT:-3008}"
     env_file:
       - apps/edr-payment-api/.env
-
 secrets:
   npmrc:
     file: .npmrc

From fa3138f2aca8fd6a906ced36b0e4d06b8e065473 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 12:54:04 +0000
Subject: [PATCH 58/63] refactor: migrate the warehouse invoice to use the
 central one

---
 apps/edr-freight-api/package.json             |   2 +-
 ...29000000000-CentralizeWarehouseInvoices.ts | 222 +++++++
 .../src/modules/billing/billing.service.ts    |  29 +-
 .../warehouse-fee-invoice-item.entity.ts      |  50 --
 .../entities/warehouse-fee-invoice.entity.ts  | 107 ----
 .../warehouse-fee-invoice-item.repository.ts  |  13 -
 .../warehouse-fee-invoice.repository.ts       |  13 -
 .../warehouses/warehouse-invoice.service.ts   | 600 ++++++++++++------
 .../warehouses/warehouse-invoice.types.ts     |  88 +++
 .../modules/warehouses/warehouses.module.ts   |  10 +-
 apps/edr-freight-api/tsconfig.json            |   1 +
 11 files changed, 744 insertions(+), 391 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts
 delete mode 100644 apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice-item.entity.ts
 delete mode 100644 apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice.entity.ts
 delete mode 100644 apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice-item.repository.ts
 delete mode 100644 apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.types.ts

diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index 71e2fd60a..9edf388b9 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -6,7 +6,7 @@
   "scripts": {
     "clean": "node -e \"const fs=require('fs'); fs.rmSync('dist',{recursive:true,force:true}); fs.rmSync('.tsbuildinfo',{force:true});\"",
     "predev": "pnpm run clean",
-    "dev": "nest start --watch",
+    "dev": "nest start --watch --clearScreen false",
     "prebuild": "pnpm run clean",
     "build": "nest build",
     "start": "node dist/main.js",
diff --git a/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts b/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts
new file mode 100644
index 000000000..dd246cb7d
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts
@@ -0,0 +1,222 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Fold warehouse fee invoices into the central billing system.
+ *
+ * Warehouse fee invoices are no longer a standalone aggregate: each becomes a
+ * global `freight.invoices` row (`source = 'warehouse'`, `source_id =
+ * inventory_id`) with its items as `freight.invoice_lines`. The warehouse
+ * service is now a thin layer over `BillingService`. This migration backfills the
+ * existing rows (preserving ids, numbers, status, amounts and payment history),
+ * then drops the two legacy tables.
+ *
+ * Rows that cannot be billed centrally — no company to bill (`company_id` /
+ * `company_profile_id` underivable from the customer or the booking) — are not
+ * migrated; they could never have been charged through the gateway and are
+ * dropped with the table.
+ */
+export class CentralizeWarehouseInvoices1829000000000 implements MigrationInterface {
+  name = 'CentralizeWarehouseInvoices1829000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // 1. Invoice headers. Keep the same id so items still link, and so any
+    //    external reference to the invoice id stays valid.
+    await queryRunner.query(`
+      INSERT INTO freight.invoices (
+        id, invoice_number, company_id, company_profile_id,
+        subtotal_amount, tax_amount, total_amount, paid_amount, balance_amount,
+        currency, status, source, source_id, type,
+        issued_at, paid_at, payments, payment_id, due_at,
+        created_at, updated_at, deleted_at
+      )
+      SELECT
+        fee.id,
+        fee.invoice_number,
+        COALESCE(fee.customer_id, b.company_id),
+        COALESCE(
+          b.company_profile_id,
+          (SELECT cp.id
+             FROM freight.company_profiles cp
+            WHERE cp.company_id = COALESCE(fee.customer_id, b.company_id)
+              AND cp.deleted_at IS NULL
+            ORDER BY cp.created_at ASC
+            LIMIT 1)
+        ),
+        fee.subtotal_amount, fee.tax_amount, fee.total_amount, fee.paid_amount, fee.balance_amount,
+        fee.currency,
+        fee.status::freight.invoices_status_enum,
+        'warehouse',
+        fee.inventory_id,
+        fee.invoice_type,
+        fee.issued_at,
+        fee.paid_at,
+        COALESCE(fee.payments, '[]'::jsonb),
+        NULL,
+        COALESCE(fee.due_date, fee.issued_at, fee.created_at),
+        fee.created_at, fee.updated_at, fee.deleted_at
+      FROM freight.warehouse_fee_invoices fee
+      LEFT JOIN freight.bookings b ON b.id = fee.booking_id
+      WHERE COALESCE(fee.customer_id, b.company_id) IS NOT NULL
+        AND COALESCE(
+          b.company_profile_id,
+          (SELECT cp.id
+             FROM freight.company_profiles cp
+            WHERE cp.company_id = COALESCE(fee.customer_id, b.company_id)
+              AND cp.deleted_at IS NULL
+            ORDER BY cp.created_at ASC
+            LIMIT 1)
+        ) IS NOT NULL
+      ON CONFLICT (id) DO NOTHING;
+    `);
+
+    // 2. Invoice lines — only for items whose parent invoice migrated. Warehouse
+    //    fee fields (fee_rule_id / chargeable_days / free_days) move into the
+    //    line's jsonb metadata.
+    await queryRunner.query(`
+      INSERT INTO freight.invoice_lines (
+        id, invoice_id, charge_type, description, quantity, unit_rate, amount,
+        currency, metadata, created_at, updated_at, deleted_at
+      )
+      SELECT
+        item.id,
+        item.invoice_id,
+        item.fee_type,
+        item.description,
+        item.quantity,
+        item.unit_rate,
+        item.amount,
+        item.currency,
+        jsonb_build_object(
+          'feeRuleId', item.fee_rule_id,
+          'chargeableDays', item.chargeable_days,
+          'freeDays', item.free_days
+        ),
+        item.created_at, item.updated_at, item.deleted_at
+      FROM freight.warehouse_fee_invoice_items item
+      JOIN freight.invoices i ON i.id = item.invoice_id AND i.source = 'warehouse'
+      ON CONFLICT (id) DO NOTHING;
+    `);
+
+    // 3. Drop the legacy tables (items first — FK to invoices).
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.warehouse_fee_invoice_items;`);
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.warehouse_fee_invoices;`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Recreate the legacy tables …
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.warehouse_fee_invoices (
+        id uuid NOT NULL DEFAULT uuid_generate_v4(),
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz,
+        invoice_number varchar(40) NOT NULL,
+        booking_id uuid,
+        customer_id uuid,
+        inventory_id uuid NOT NULL,
+        facility_id uuid,
+        warehouse_id uuid,
+        yard_id uuid,
+        zone_id uuid,
+        invoice_type varchar(32) NOT NULL DEFAULT 'MIXED_WAREHOUSE_FEES',
+        status varchar(20) NOT NULL DEFAULT 'DRAFT',
+        subtotal_amount numeric(14,2) NOT NULL DEFAULT 0,
+        tax_amount numeric(14,2) NOT NULL DEFAULT 0,
+        total_amount numeric(14,2) NOT NULL DEFAULT 0,
+        paid_amount numeric(14,2) NOT NULL DEFAULT 0,
+        balance_amount numeric(14,2) NOT NULL DEFAULT 0,
+        currency varchar(8) NOT NULL DEFAULT 'USD',
+        period_start timestamptz,
+        period_end timestamptz,
+        issued_at timestamptz,
+        due_date timestamptz,
+        paid_at timestamptz,
+        cancelled_at timestamptz,
+        payments jsonb NOT NULL DEFAULT '[]',
+        notes text,
+        CONSTRAINT "PK_warehouse_fee_invoices" PRIMARY KEY (id),
+        CONSTRAINT "UQ_warehouse_fee_invoices_invoice_number" UNIQUE (invoice_number)
+      );
+    `);
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_booking_id" ON freight.warehouse_fee_invoices (booking_id);`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_inventory_id" ON freight.warehouse_fee_invoices (inventory_id);`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_status" ON freight.warehouse_fee_invoices (status);`,
+    );
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.warehouse_fee_invoice_items (
+        id uuid NOT NULL DEFAULT uuid_generate_v4(),
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz,
+        invoice_id uuid NOT NULL,
+        fee_rule_id uuid,
+        fee_type varchar(32) NOT NULL,
+        description varchar(255) NOT NULL,
+        quantity numeric(12,2) NOT NULL DEFAULT 1,
+        unit_rate numeric(14,2) NOT NULL DEFAULT 0,
+        amount numeric(14,2) NOT NULL DEFAULT 0,
+        currency varchar(8) NOT NULL DEFAULT 'USD',
+        chargeable_days int,
+        free_days int,
+        CONSTRAINT "PK_warehouse_fee_invoice_items" PRIMARY KEY (id),
+        CONSTRAINT "FK_warehouse_fee_invoice_items_invoice"
+          FOREIGN KEY (invoice_id) REFERENCES freight.warehouse_fee_invoices (id) ON DELETE CASCADE
+      );
+    `);
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoice_items_invoice_id" ON freight.warehouse_fee_invoice_items (invoice_id);`,
+    );
+
+    // … then copy the warehouse-source invoices back, deriving the typed FKs and
+    // period from the linked inventory item.
+    await queryRunner.query(`
+      INSERT INTO freight.warehouse_fee_invoices (
+        id, created_at, updated_at, deleted_at, invoice_number,
+        booking_id, customer_id, inventory_id, facility_id, warehouse_id, yard_id, zone_id,
+        invoice_type, status, subtotal_amount, tax_amount, total_amount, paid_amount, balance_amount,
+        currency, period_start, period_end, issued_at, due_date, paid_at, cancelled_at, payments, notes
+      )
+      SELECT
+        i.id, i.created_at, i.updated_at, i.deleted_at, i.invoice_number,
+        inv.booking_id, i.company_id, i.source_id, w.facility_id, inv.warehouse_id, inv.yard_id, inv.zone_id,
+        i.type, i.status::text, i.subtotal_amount, i.tax_amount, i.total_amount, i.paid_amount, i.balance_amount,
+        i.currency, inv.arrived_at, i.issued_at, i.issued_at, i.due_at, i.paid_at,
+        CASE WHEN i.status::text = 'CANCELLED' THEN i.updated_at ELSE NULL END,
+        i.payments, NULL
+      FROM freight.invoices i
+      LEFT JOIN freight.warehouse_inventory inv ON inv.id = i.source_id
+      LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
+      WHERE i.source = 'warehouse'
+      ON CONFLICT (id) DO NOTHING;
+    `);
+    await queryRunner.query(`
+      INSERT INTO freight.warehouse_fee_invoice_items (
+        id, created_at, updated_at, deleted_at, invoice_id, fee_rule_id, fee_type,
+        description, quantity, unit_rate, amount, currency, chargeable_days, free_days
+      )
+      SELECT
+        l.id, l.created_at, l.updated_at, l.deleted_at, l.invoice_id,
+        NULLIF(l.metadata->>'feeRuleId', '')::uuid,
+        l.charge_type,
+        COALESCE(l.description, ''),
+        l.quantity, l.unit_rate, l.amount, l.currency,
+        NULLIF(l.metadata->>'chargeableDays', '')::int,
+        NULLIF(l.metadata->>'freeDays', '')::int
+      FROM freight.invoice_lines l
+      JOIN freight.invoices i ON i.id = l.invoice_id AND i.source = 'warehouse'
+      ON CONFLICT (id) DO NOTHING;
+    `);
+
+    // Remove the migrated rows from the central tables.
+    await queryRunner.query(`
+      DELETE FROM freight.invoice_lines
+       WHERE invoice_id IN (SELECT id FROM freight.invoices WHERE source = 'warehouse');
+    `);
+    await queryRunner.query(`DELETE FROM freight.invoices WHERE source = 'warehouse';`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index edacc2c79..e4389e7cf 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,3 +1,4 @@
+import { Freight, PaymentReferenceType } from "@edr/types";
 import {
   BadRequestException,
   forwardRef,
@@ -7,22 +8,21 @@ import {
   NotFoundException,
 } from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
-import { Freight, PaymentReferenceType } from "@edr/types";
 import { DataSource, EntityManager, In } from "typeorm";
 
-import { Invoice, InvoicePayment } from "./entities/invoice.entity";
-import { InvoiceLine } from "./entities/invoice-line.entity";
-import { InvoiceRepository } from "./invoice.repository";
-import { InvoiceLineRepository } from "./invoice-line.repository";
-import { nextDailyInvoiceNumber } from "./invoice-numbering.util";
-import { applySettlement, round2 } from "./invoice-settlement.util";
+import { CompaniesService } from "../companies/companies.service";
+import { PaymentService } from "../payment/payment.service";
+import { InitiateResponseDto } from "../payment/payments.dto";
 import {
   InvoiceDocumentModel,
   InvoiceDocumentService,
 } from "./documents/invoice-document.service";
-import { PaymentService } from "../payment/payment.service";
-import { InitiateResponseDto } from "../payment/payments.dto";
-import { CompaniesService } from "../companies/companies.service";
+import { InvoiceLine } from "./entities/invoice-line.entity";
+import { Invoice, InvoicePayment } from "./entities/invoice.entity";
+import { InvoiceLineRepository } from "./invoice-line.repository";
+import { nextDailyInvoiceNumber } from "./invoice-numbering.util";
+import { applySettlement, round2 } from "./invoice-settlement.util";
+import { InvoiceRepository } from "./invoice.repository";
 
 /** Options forwarded to the payment gateway when settling an invoice. */
 export interface PayInvoiceOptions {
@@ -96,6 +96,11 @@ export interface GenerateInvoiceInput {
    * (default PENDING) stamps `issuedAt`.
    */
   status?: Freight.InvoiceStatus;
+  /**
+   * Document number prefix for this source (e.g. `WHF` for warehouse fees);
+   * defaults to `FRT`. The daily sequence is allocated per prefix.
+   */
+  numberCode?: string;
 }
 
 /** Payload broadcast on `${source}.invoice.<event>`. */
@@ -269,9 +274,9 @@ export class BillingService {
 
   // ── Generation ───────────────────────────────────────────────────────────────
 
-  /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */
+  /** `<CODE>-YYYYMMDD-00001` — sequential per day & prefix, within the active transaction. */
   private nextInvoiceNumber(mg: EntityManager): Promise<string> {
-    return nextDailyInvoiceNumber(mg, { table: "freight.invoices", code: "FRT" });
+    return nextDailyInvoiceNumber(mg, { table: "freight.invoices", code:"INV" });
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice-item.entity.ts b/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice-item.entity.ts
deleted file mode 100644
index 8b14dcea3..000000000
--- a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice-item.entity.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
-
-import { WarehouseFeeInvoice } from './warehouse-fee-invoice.entity';
-
-export const WAREHOUSE_FEE_TYPES = [
-  'CONTAINER_DEMURRAGE',
-  'BULK_DEMURRAGE',
-  'STORAGE_FEE',
-  'HANDLING_FEE',
-] as const;
-export type WarehouseFeeType = (typeof WAREHOUSE_FEE_TYPES)[number];
-
-@Entity({ schema: 'freight', name: 'warehouse_fee_invoice_items' })
-@Index(['invoiceId'])
-export class WarehouseFeeInvoiceItem extends BaseEntity {
-  @Column({ name: 'invoice_id', type: 'uuid' })
-  invoiceId!: string;
-
-  @ManyToOne(() => WarehouseFeeInvoice, { onDelete: 'CASCADE' })
-  @JoinColumn({ name: 'invoice_id' })
-  invoice?: WarehouseFeeInvoice;
-
-  @Column({ name: 'fee_rule_id', type: 'uuid', nullable: true })
-  feeRuleId?: string | null;
-
-  @Column({ name: 'fee_type', type: 'varchar', length: 32 })
-  feeType!: WarehouseFeeType;
-
-  @Column({ name: 'description', type: 'varchar', length: 255 })
-  description!: string;
-
-  @Column({ name: 'quantity', type: 'numeric', precision: 12, scale: 2, default: 1 })
-  quantity!: number;
-
-  @Column({ name: 'unit_rate', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  unitRate!: number;
-
-  @Column({ name: 'amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  amount!: number;
-
-  @Column({ name: 'currency', type: 'varchar', length: 8, default: 'USD' })
-  currency!: string;
-
-  @Column({ name: 'chargeable_days', type: 'int', nullable: true })
-  chargeableDays?: number | null;
-
-  @Column({ name: 'free_days', type: 'int', nullable: true })
-  freeDays?: number | null;
-}
diff --git a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice.entity.ts b/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice.entity.ts
deleted file mode 100644
index e57d626d5..000000000
--- a/apps/edr-freight-api/src/modules/warehouses/entities/warehouse-fee-invoice.entity.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index } from 'typeorm';
-
-export const WAREHOUSE_INVOICE_TYPES = ['DEMURRAGE', 'STORAGE_FEE', 'MIXED_WAREHOUSE_FEES'] as const;
-export type WarehouseInvoiceType = (typeof WAREHOUSE_INVOICE_TYPES)[number];
-
-export const WAREHOUSE_INVOICE_STATUSES = [
-  'DRAFT',
-  'ISSUED',
-  'PARTIALLY_PAID',
-  'PAID',
-  'CANCELLED',
-] as const;
-export type WarehouseInvoiceStatus = (typeof WAREHOUSE_INVOICE_STATUSES)[number];
-
-/** A single recorded payment against a warehouse fee invoice (history). */
-export interface WarehouseInvoicePayment {
-  amount: number;
-  method?: string | null;
-  reference?: string | null;
-  paidAt: string;
-}
-
-/**
- * Batch 6 — invoice generated from Batch 5 demurrage/storage fee calculation.
- * Owns warehouse fees; links to booking/customer/inventory/location so it can
- * connect to the existing payment module without duplicating it.
- */
-@Entity({ schema: 'freight', name: 'warehouse_fee_invoices' })
-@Index(['invoiceNumber'], { unique: true })
-@Index(['bookingId'])
-@Index(['inventoryId'])
-@Index(['status'])
-export class WarehouseFeeInvoice extends BaseEntity {
-  @Column({ name: 'invoice_number', type: 'varchar', length: 40, unique: true })
-  invoiceNumber!: string;
-
-  @Column({ name: 'booking_id', type: 'uuid', nullable: true })
-  bookingId?: string | null;
-
-  @Column({ name: 'customer_id', type: 'uuid', nullable: true })
-  customerId?: string | null;
-
-  @Column({ name: 'inventory_id', type: 'uuid' })
-  inventoryId!: string;
-
-  @Column({ name: 'facility_id', type: 'uuid', nullable: true })
-  facilityId?: string | null;
-
-  @Column({ name: 'warehouse_id', type: 'uuid', nullable: true })
-  warehouseId?: string | null;
-
-  @Column({ name: 'yard_id', type: 'uuid', nullable: true })
-  yardId?: string | null;
-
-  @Column({ name: 'zone_id', type: 'uuid', nullable: true })
-  zoneId?: string | null;
-
-  @Column({ name: 'invoice_type', type: 'varchar', length: 32, default: 'MIXED_WAREHOUSE_FEES' })
-  invoiceType!: WarehouseInvoiceType;
-
-  @Column({ name: 'status', type: 'varchar', length: 20, default: 'DRAFT' })
-  status!: WarehouseInvoiceStatus;
-
-  @Column({ name: 'subtotal_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  subtotalAmount!: number;
-
-  @Column({ name: 'tax_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  taxAmount!: number;
-
-  @Column({ name: 'total_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  totalAmount!: number;
-
-  @Column({ name: 'paid_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  paidAmount!: number;
-
-  @Column({ name: 'balance_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
-  balanceAmount!: number;
-
-  @Column({ name: 'currency', type: 'varchar', length: 8, default: 'USD' })
-  currency!: string;
-
-  /** Charge window covered by this invoice — used to allow a later invoice for a new period. */
-  @Column({ name: 'period_start', type: 'timestamptz', nullable: true })
-  periodStart?: Date | null;
-
-  @Column({ name: 'period_end', type: 'timestamptz', nullable: true })
-  periodEnd?: Date | null;
-
-  @Column({ name: 'issued_at', type: 'timestamptz', nullable: true })
-  issuedAt?: Date | null;
-
-  @Column({ name: 'due_date', type: 'timestamptz', nullable: true })
-  dueDate?: Date | null;
-
-  @Column({ name: 'paid_at', type: 'timestamptz', nullable: true })
-  paidAt?: Date | null;
-
-  @Column({ name: 'cancelled_at', type: 'timestamptz', nullable: true })
-  cancelledAt?: Date | null;
-
-  @Column({ name: 'payments', type: 'jsonb', default: () => "'[]'" })
-  payments!: WarehouseInvoicePayment[];
-
-  @Column({ name: 'notes', type: 'text', nullable: true })
-  notes?: string | null;
-}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice-item.repository.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice-item.repository.ts
deleted file mode 100644
index 5b5df396e..000000000
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice-item.repository.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { BaseRepository } from '@edr/api-common';
-import { Injectable } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-
-import { WarehouseFeeInvoiceItem } from './entities/warehouse-fee-invoice-item.entity';
-
-@Injectable()
-export class WarehouseFeeInvoiceItemRepository extends BaseRepository<WarehouseFeeInvoiceItem> {
-  constructor(@InjectRepository(WarehouseFeeInvoiceItem) repository: Repository<WarehouseFeeInvoiceItem>) {
-    super(repository);
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice.repository.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice.repository.ts
deleted file mode 100644
index 97328f46d..000000000
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-fee-invoice.repository.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { BaseRepository } from '@edr/api-common';
-import { Injectable } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-
-import { WarehouseFeeInvoice } from './entities/warehouse-fee-invoice.entity';
-
-@Injectable()
-export class WarehouseFeeInvoiceRepository extends BaseRepository<WarehouseFeeInvoice> {
-  constructor(@InjectRepository(WarehouseFeeInvoice) repository: Repository<WarehouseFeeInvoice>) {
-    super(repository);
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
index 904728251..9b349181d 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
@@ -1,22 +1,23 @@
 import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { Freight } from '@edr/types';
 import { DataSource } from 'typeorm';
 
+import { BillingService, InvoiceLineInput } from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { InvoiceLine } from '../billing/entities/invoice-line.entity';
 import {
   InvoiceDocumentModel,
   InvoiceDocumentService,
 } from '../billing/documents/invoice-document.service';
-import { nextDailyInvoiceNumber } from '../billing/invoice-numbering.util';
-import { applySettlement } from '../billing/invoice-settlement.util';
 import { NotificationsService } from '../notifications/notifications.service';
+import { WarehouseFeeService } from './warehouse-fee.service';
 import {
-  WarehouseFeeInvoice,
+  WarehouseFeeInvoiceView,
+  WarehouseFeeType,
+  WarehouseInvoiceItemView,
   WarehouseInvoiceStatus,
   WarehouseInvoiceType,
-} from './entities/warehouse-fee-invoice.entity';
-import { WarehouseFeeType } from './entities/warehouse-fee-invoice-item.entity';
-import { WarehouseFeeInvoiceItemRepository } from './warehouse-fee-invoice-item.repository';
-import { WarehouseFeeInvoiceRepository } from './warehouse-fee-invoice.repository';
-import { WarehouseFeeService } from './warehouse-fee.service';
+} from './warehouse-invoice.types';
 
 interface GenerateOptions {
   confirmZero?: boolean;
@@ -32,9 +33,20 @@ export interface PayInvoiceDto {
   driverPhone?: string;
 }
 
-/** Invoices that still owe money and therefore block terminal release. */
-const BLOCKING_STATUSES: WarehouseInvoiceStatus[] = ['ISSUED', 'PARTIALLY_PAID'];
-const ACTIVE_STATUSES: WarehouseInvoiceStatus[] = ['ISSUED', 'PARTIALLY_PAID', 'PAID'];
+/** Warehouse fee invoices live in the global billing system under this source. */
+const SOURCE = Freight.InvoiceSource.Warehouse;
+/** Document number prefix kept for warehouse fee invoices (e.g. `WHF-20260630-00001`). */
+const NUMBER_CODE = 'WHF';
+
+/** Global statuses that still owe money and therefore block terminal release. */
+const BLOCKING_STATUSES: Freight.InvoiceStatus[] = [
+  Freight.InvoiceStatus.Issued,
+  Freight.InvoiceStatus.Pending,
+  Freight.InvoiceStatus.PartiallyPaid,
+  Freight.InvoiceStatus.Overdue,
+];
+/** Global statuses considered an "active" invoice for per-inventory dedup. */
+const ACTIVE_STATUSES: Freight.InvoiceStatus[] = [...BLOCKING_STATUSES, Freight.InvoiceStatus.Paid];
 
 export interface InvoiceDocumentDetails {
   bookingReference: string | null;
@@ -50,28 +62,75 @@ export interface InvoiceDocumentDetails {
   zoneName: string | null;
 }
 
-export type WarehouseFeeInvoiceWithDisplay = WarehouseFeeInvoice & Partial<InvoiceDocumentDetails>;
+export type WarehouseFeeInvoiceDetail = WarehouseFeeInvoiceView &
+  Partial<InvoiceDocumentDetails> & { items: WarehouseInvoiceItemView[] };
 
+/** The warehouse-specific columns derived from the linked inventory item. */
+interface InventoryContext {
+  bookingId: string | null;
+  facilityId: string | null;
+  warehouseId: string | null;
+  yardId: string | null;
+  zoneId: string | null;
+  periodStart: Date | null;
+}
+
+/** Source fields a view is projected from — satisfied by the global {@link Invoice}. */
+interface ViewSource {
+  id: string;
+  invoiceNumber: string;
+  companyId: string;
+  sourceId: string;
+  type: string;
+  status: Freight.InvoiceStatus | string;
+  subtotalAmount: number | string;
+  taxAmount: number | string;
+  totalAmount: number | string;
+  paidAmount: number | string;
+  balanceAmount: number | string;
+  currency: string;
+  issuedAt?: Date | null;
+  dueAt?: Date | null;
+  paidAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  payments?: Array<{
+    amount: number | string;
+    method?: string | null;
+    reference?: string | null;
+    paidAt: string;
+  }> | null;
+}
+
+/**
+ * Thin warehouse layer over the central {@link BillingService}. Warehouse fee
+ * invoices are global `Invoice` rows (`source = warehouse`, `sourceId =
+ * inventoryId`); this service owns only the warehouse-specific concerns —
+ * computing fees, per-inventory dedup, release-blocking, SMS notifications, the
+ * sealed PDF, and reshaping the global invoice back into the historical
+ * `WarehouseFeeInvoice` JSON the portal/backoffice expect. All money, numbering,
+ * status, and payment math live in billing.
+ */
 @Injectable()
 export class WarehouseInvoiceService {
   private readonly logger = new Logger(WarehouseInvoiceService.name);
 
   constructor(
     private readonly dataSource: DataSource,
-    private readonly invoiceRepository: WarehouseFeeInvoiceRepository,
-    private readonly itemRepository: WarehouseFeeInvoiceItemRepository,
-    private readonly feeService: WarehouseFeeService,
+    private readonly billing: BillingService,
     private readonly invoiceDocuments: InvoiceDocumentService,
+    private readonly feeService: WarehouseFeeService,
     private readonly notifications: NotificationsService,
   ) {}
 
   // ── Generation ───────────────────────────────────────────────────────────
-  async generateForInventory(inventoryId: string, opts: GenerateOptions = {}): Promise<WarehouseFeeInvoice> {
+  async generateForInventory(inventoryId: string, opts: GenerateOptions = {}): Promise<WarehouseFeeInvoiceDetail> {
     const [item] = await this.dataSource.query(
       `SELECT inv.id, inv.booking_id AS "bookingId", inv.warehouse_id AS "warehouseId",
               inv.yard_id AS "yardId", inv.zone_id AS "zoneId", inv.arrived_at AS "arrivedAt",
               w.facility_id AS "facilityId",
-              b.company_id AS "customerId", b.freight_type AS "freightType"
+              b.company_id AS "companyId", b.company_profile_id AS "companyProfileId",
+              b.freight_type AS "freightType"
          FROM freight.warehouse_inventory inv
          LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
          LEFT JOIN freight.bookings b ON b.id = inv.booking_id
@@ -80,9 +139,16 @@ export class WarehouseInvoiceService {
     );
     if (!item) throw new NotFoundException(`Inventory item ${inventoryId} not found`);
 
+    // Routing through the global invoice requires a billable company + profile,
+    // both of which come from the inventory's booking.
+    if (!item.companyId || !item.companyProfileId) {
+      throw new BadRequestException(
+        'Cannot generate a warehouse fee invoice: the inventory item has no billable company (no associated booking).',
+      );
+    }
+
     // Dedup: only one active (non-cancelled) invoice per inventory item.
-    const active = await this.invoiceRepository.findAll({ where: { inventoryId } });
-    if (active.some((inv) => ACTIVE_STATUSES.includes(inv.status))) {
+    if (await this.hasActiveInvoice(inventoryId)) {
       throw new ConflictException(
         'An active warehouse fee invoice already exists for this item. Cancel it before generating a new one.',
       );
@@ -117,9 +183,7 @@ export class WarehouseInvoiceService {
         };
       });
 
-    const subtotal = items.reduce((s, i) => s + i.amount, 0);
-    const total = subtotal; // tax model can be layered on later
-
+    const total = items.reduce((s, i) => s + i.amount, 0);
     if (total <= 0 && !opts.confirmZero) {
       throw new BadRequestException('No payable warehouse fee found for this item.');
     }
@@ -129,58 +193,77 @@ export class WarehouseInvoiceService {
     const invoiceType: WarehouseInvoiceType =
       hasDemurrage && hasStorage ? 'MIXED_WAREHOUSE_FEES' : hasStorage ? 'STORAGE_FEE' : 'DEMURRAGE';
 
-    const currency = billingCurrency;
-    const now = new Date();
-    const periodEnd = previews[0] ? new Date(previews[0].endDate) : now;
+    const lines: InvoiceLineInput[] = items.map((it) => ({
+      chargeType: it.feeType,
+      description: it.description,
+      quantity: it.quantity,
+      unitRate: it.unitRate,
+      amount: it.amount,
+      currency: it.currency,
+      metadata: {
+        feeRuleId: it.feeRuleId ?? null,
+        chargeableDays: it.chargeableDays ?? null,
+        freeDays: it.freeDays ?? null,
+      },
+    }));
 
-    const invoice = await this.invoiceRepository.create({
-      invoiceNumber: await this.nextInvoiceNumber(),
-      bookingId: item.bookingId ?? null,
-      customerId: item.customerId ?? null,
-      inventoryId,
-      facilityId: item.facilityId ?? null,
-      warehouseId: item.warehouseId ?? null,
-      yardId: item.yardId ?? null,
-      zoneId: item.zoneId ?? null,
-      invoiceType,
-      status: 'ISSUED',
-      subtotalAmount: subtotal,
-      taxAmount: 0,
-      totalAmount: total,
-      paidAmount: 0,
-      balanceAmount: total,
-      currency,
-      periodStart: item.arrivedAt ?? null,
-      periodEnd,
-      issuedAt: now,
-      payments: [],
-      notes: opts.performedBy ? `Generated by ${opts.performedBy}` : null,
+    const invoice = await this.billing.generateInvoice({
+      source: SOURCE,
+      sourceId: inventoryId,
+      type: invoiceType,
+      companyId: item.companyId,
+      companyProfileId: item.companyProfileId,
+      currency: billingCurrency,
+      lines,
+      status: Freight.InvoiceStatus.Issued,
+      numberCode: NUMBER_CODE,
     });
 
-    for (const it of items) {
-      await this.itemRepository.create({ invoiceId: invoice.id, ...it });
-    }
-
-    const saved = await this.findById(invoice.id);
-    await this.notifyWarehouseFeeIssued(saved);
-    return saved;
-  }
-
-  /** WHF-YYYYMMDD-00001 — sequential per day (shared billing numbering). */
-  private nextInvoiceNumber(): Promise<string> {
-    return nextDailyInvoiceNumber(this.dataSource, {
-      table: 'freight.warehouse_fee_invoices',
-      code: 'WHF',
-    });
+    const detail = await this.findById(invoice.id);
+    await this.notifyWarehouseFeeIssued(detail);
+    return detail;
   }
 
   // ── Reads ────────────────────────────────────────────────────────────────
-  async findById(id: string): Promise<WarehouseFeeInvoiceWithDisplay & { items: unknown[] }> {
-    const invoice = await this.invoiceRepository.findById(id);
-    if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
-    const items = await this.itemRepository.findAll({ where: { invoiceId: id } });
+  async findById(id: string): Promise<WarehouseFeeInvoiceDetail> {
+    const invoice = await this.loadWarehouseInvoice(id);
+    const ctx = await this.getInventoryContext(invoice.sourceId);
     const details = await this.getInvoiceDocumentDetails(invoice);
-    return { ...invoice, ...details, items } as WarehouseFeeInvoiceWithDisplay & { items: unknown[] };
+    const items = invoice.lines.map((l) => this.lineToItem(l));
+    return { ...this.buildView(invoice, ctx), ...details, items };
+  }
+
+  listForInventory(inventoryId: string): Promise<WarehouseFeeInvoiceView[]> {
+    return this.queryViews('AND i.source_id = $1', [inventoryId]);
+  }
+
+  listForBooking(bookingId: string): Promise<WarehouseFeeInvoiceView[]> {
+    return this.queryViews('AND inv.booking_id = $1', [bookingId]);
+  }
+
+  async findAll(
+    filter: Partial<
+      Pick<
+        WarehouseFeeInvoiceView,
+        'status' | 'invoiceType' | 'warehouseId' | 'facilityId' | 'customerId' | 'bookingId'
+      >
+    >,
+  ): Promise<WarehouseFeeInvoiceView[]> {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+    const add = (sql: (p: string) => string, value: unknown) => {
+      params.push(value);
+      conditions.push(sql(`$${params.length}`));
+    };
+
+    if (filter.status) add((p) => `i.status::text = ${p}`, this.toGlobalStatus(filter.status as WarehouseInvoiceStatus));
+    if (filter.invoiceType) add((p) => `i.type = ${p}`, filter.invoiceType);
+    if (filter.customerId) add((p) => `i.company_id = ${p}`, filter.customerId);
+    if (filter.warehouseId) add((p) => `inv.warehouse_id = ${p}`, filter.warehouseId);
+    if (filter.facilityId) add((p) => `w.facility_id = ${p}`, filter.facilityId);
+    if (filter.bookingId) add((p) => `inv.booking_id = ${p}`, filter.bookingId);
+
+    return this.queryViews(conditions.map((c) => `AND ${c}`).join(' '), params);
   }
 
   async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
@@ -196,20 +279,219 @@ export class WarehouseInvoiceService {
     return this.invoiceDocuments.render(this.toDocumentModel(invoice, 'RECEIPT'));
   }
 
-  /** Map a warehouse fee invoice (with display details + items) onto the shared document model. */
+  // ── State changes ────────────────────────────────────────────────────────
+  async cancel(id: string): Promise<WarehouseFeeInvoiceDetail> {
+    const invoice = await this.loadWarehouseInvoice(id);
+    if (invoice.status === Freight.InvoiceStatus.Paid) {
+      throw new BadRequestException('A paid invoice cannot be cancelled.');
+    }
+    await this.billing.cancelInvoice(id);
+    return this.findById(id);
+  }
+
+  /** Record a payment against the invoice (delegates settlement to billing). */
+  async pay(id: string, dto: PayInvoiceDto): Promise<WarehouseFeeInvoiceDetail> {
+    // Guard that this is a warehouse invoice before recording (404 otherwise).
+    await this.loadWarehouseInvoice(id);
+    await this.billing.recordPayment(id, {
+      amount: dto.amount,
+      method: dto.method ?? null,
+      reference: dto.reference ?? null,
+      metadata:
+        dto.driverName || dto.driverPhone
+          ? { driverName: dto.driverName ?? null, driverPhone: dto.driverPhone ?? null }
+          : null,
+    });
+    const detail = await this.findById(id);
+    await this.notifyWarehouseFeePayment(detail, dto);
+    return detail;
+  }
+
+  // ── Release blocking ──────────────────────────────────────────────────────
+  /** Returns the first unpaid invoice that blocks terminal release, or null. */
+  async findBlockingInvoice(inventoryId: string): Promise<WarehouseFeeInvoiceView | null> {
+    const blocking = await this.queryViews(
+      `AND i.source_id = $1 AND i.status::text = ANY($2::text[])`,
+      [inventoryId, BLOCKING_STATUSES],
+    );
+    return blocking[0] ?? null;
+  }
+
+  async assertClearanceAllowed(inventoryId: string): Promise<void> {
+    const invoices = await this.queryViews('AND i.source_id = $1', [inventoryId]);
+    const blocking = invoices.find((inv) => inv.status === 'ISSUED' || inv.status === 'PARTIALLY_PAID');
+    if (blocking) {
+      throw new BadRequestException(
+        `Warehouse demurrage/storage invoice ${blocking.invoiceNumber} must be fully paid before terminal release.`,
+      );
+    }
+
+    if (invoices.some((inv) => inv.status === 'PAID')) return;
+
+    const previews = await this.feeService.previewForInventory(inventoryId, 'USD');
+    const payableAmount = previews.reduce((sum, fee) => sum + Number(fee.amount || 0), 0);
+    if (payableAmount > 0) {
+      throw new BadRequestException(
+        'Generate and fully pay the warehouse demurrage/storage invoice before terminal release.',
+      );
+    }
+  }
+
+  // ── Internal: loading & projection ─────────────────────────────────────────
+
+  /** Load a global invoice (+lines) and assert it is a warehouse fee invoice. */
+  private async loadWarehouseInvoice(id: string): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const invoice = await this.billing.findById(id);
+    if (invoice.source !== SOURCE) {
+      throw new NotFoundException(`Invoice ${id} not found`);
+    }
+    return invoice;
+  }
+
+  private async hasActiveInvoice(inventoryId: string): Promise<boolean> {
+    const [row] = await this.dataSource.query(
+      `SELECT 1
+         FROM freight.invoices
+        WHERE source = $1 AND source_id = $2 AND status::text = ANY($3::text[]) AND deleted_at IS NULL
+        LIMIT 1`,
+      [SOURCE, inventoryId, ACTIVE_STATUSES],
+    );
+    return Boolean(row);
+  }
+
+  /**
+   * Project warehouse-source global invoices into the historical view, joined to
+   * their inventory item for the typed FKs. Powers every list/filter read.
+   */
+  private async queryViews(extraWhere: string, params: unknown[]): Promise<WarehouseFeeInvoiceView[]> {
+    const rows = await this.dataSource.query(
+      `SELECT i.id, i.invoice_number AS "invoiceNumber", i.company_id AS "companyId",
+              i.source_id AS "sourceId", i.type, i.status,
+              i.subtotal_amount AS "subtotalAmount", i.tax_amount AS "taxAmount",
+              i.total_amount AS "totalAmount", i.paid_amount AS "paidAmount",
+              i.balance_amount AS "balanceAmount", i.currency, i.payments,
+              i.issued_at AS "issuedAt", i.due_at AS "dueAt", i.paid_at AS "paidAt",
+              i.created_at AS "createdAt", i.updated_at AS "updatedAt",
+              inv.booking_id AS "bookingId", inv.warehouse_id AS "warehouseId",
+              inv.yard_id AS "yardId", inv.zone_id AS "zoneId", inv.arrived_at AS "periodStart",
+              w.facility_id AS "facilityId"
+         FROM freight.invoices i
+         LEFT JOIN freight.warehouse_inventory inv ON inv.id = i.source_id AND inv.deleted_at IS NULL
+         LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
+        WHERE i.source = $${params.length + 1} AND i.deleted_at IS NULL ${extraWhere}
+        ORDER BY i.created_at DESC`,
+      [...params, SOURCE],
+    );
+
+    return (rows as Array<ViewSource & InventoryContext>).map((row) =>
+      this.buildView(row, {
+        bookingId: row.bookingId ?? null,
+        facilityId: row.facilityId ?? null,
+        warehouseId: row.warehouseId ?? null,
+        yardId: row.yardId ?? null,
+        zoneId: row.zoneId ?? null,
+        periodStart: row.periodStart ?? null,
+      }),
+    );
+  }
+
+  /** Reshape a global invoice (+ derived inventory context) into the warehouse view. */
+  private buildView(inv: ViewSource, ctx: InventoryContext): WarehouseFeeInvoiceView {
+    const status = this.toWarehouseStatus(inv.status);
+    return {
+      id: inv.id,
+      invoiceNumber: inv.invoiceNumber,
+      bookingId: ctx.bookingId,
+      customerId: inv.companyId ?? null,
+      inventoryId: inv.sourceId,
+      facilityId: ctx.facilityId,
+      warehouseId: ctx.warehouseId,
+      yardId: ctx.yardId,
+      zoneId: ctx.zoneId,
+      invoiceType: inv.type as WarehouseInvoiceType,
+      status,
+      subtotalAmount: Number(inv.subtotalAmount),
+      taxAmount: Number(inv.taxAmount),
+      totalAmount: Number(inv.totalAmount),
+      paidAmount: Number(inv.paidAmount),
+      balanceAmount: Number(inv.balanceAmount),
+      currency: inv.currency,
+      periodStart: ctx.periodStart,
+      // No standalone period column once centralized: the charge window ends at
+      // issuance, so `issuedAt` is the period end.
+      periodEnd: inv.issuedAt ?? null,
+      issuedAt: inv.issuedAt ?? null,
+      dueDate: inv.dueAt ?? null,
+      paidAt: inv.paidAt ?? null,
+      cancelledAt: status === 'CANCELLED' ? inv.updatedAt : null,
+      payments: (inv.payments ?? []).map((p) => ({
+        amount: Number(p.amount),
+        method: p.method ?? null,
+        reference: p.reference ?? null,
+        paidAt: p.paidAt,
+      })),
+      notes: null,
+      createdAt: inv.createdAt,
+      updatedAt: inv.updatedAt,
+    };
+  }
+
+  private lineToItem(line: InvoiceLine): WarehouseInvoiceItemView {
+    const meta = (line.metadata ?? {}) as {
+      feeRuleId?: string | null;
+      chargeableDays?: number | null;
+      freeDays?: number | null;
+    };
+    return {
+      feeRuleId: meta.feeRuleId ?? null,
+      feeType: line.chargeType as WarehouseFeeType,
+      description: line.description ?? '',
+      quantity: Number(line.quantity),
+      unitRate: Number(line.unitRate),
+      amount: Number(line.amount),
+      currency: line.currency,
+      chargeableDays: meta.chargeableDays ?? null,
+      freeDays: meta.freeDays ?? null,
+    };
+  }
+
+  private toWarehouseStatus(status: Freight.InvoiceStatus | string): WarehouseInvoiceStatus {
+    switch (status) {
+      case Freight.InvoiceStatus.Draft:
+        return 'DRAFT';
+      case Freight.InvoiceStatus.PartiallyPaid:
+        return 'PARTIALLY_PAID';
+      case Freight.InvoiceStatus.Paid:
+        return 'PAID';
+      case Freight.InvoiceStatus.Cancelled:
+      case Freight.InvoiceStatus.Refunded:
+        return 'CANCELLED';
+      default:
+        // Issued / Pending / Overdue → an issued, still-owed invoice.
+        return 'ISSUED';
+    }
+  }
+
+  private toGlobalStatus(status: WarehouseInvoiceStatus): Freight.InvoiceStatus {
+    switch (status) {
+      case 'DRAFT':
+        return Freight.InvoiceStatus.Draft;
+      case 'PARTIALLY_PAID':
+        return Freight.InvoiceStatus.PartiallyPaid;
+      case 'PAID':
+        return Freight.InvoiceStatus.Paid;
+      case 'CANCELLED':
+        return Freight.InvoiceStatus.Cancelled;
+      default:
+        return Freight.InvoiceStatus.Issued;
+    }
+  }
+
+  /** Map a warehouse fee invoice view onto the shared document model. */
   private toDocumentModel(
-    invoice: WarehouseFeeInvoiceWithDisplay & { items: unknown[] },
+    invoice: WarehouseFeeInvoiceDetail,
     kind: 'INVOICE' | 'RECEIPT',
   ): InvoiceDocumentModel {
-    const items = invoice.items as Array<{
-      description?: string;
-      feeType?: string;
-      quantity?: number;
-      unitRate?: number;
-      amount?: number;
-      currency?: string;
-      chargeableDays?: number | null;
-    }>;
     const lastPayment = [...(invoice.payments ?? [])].pop();
     const date = (value: unknown) =>
       value ? new Date(value as string | Date).toLocaleDateString('en-GB') : null;
@@ -241,7 +523,7 @@ export class WarehouseInvoiceService {
         },
       ],
       categoryHeader: 'Fee type',
-      lines: items.map((item) => ({
+      lines: invoice.items.map((item) => ({
         description: item.description ?? null,
         category: item.feeType ?? null,
         quantity: item.quantity ?? item.chargeableDays ?? 0,
@@ -259,92 +541,14 @@ export class WarehouseInvoiceService {
     };
   }
 
-  listForInventory(inventoryId: string): Promise<WarehouseFeeInvoice[]> {
-    return this.invoiceRepository.findAll({ where: { inventoryId }, order: { createdAt: 'DESC' } });
-  }
-
-  listForBooking(bookingId: string): Promise<WarehouseFeeInvoice[]> {
-    return this.invoiceRepository.findAll({ where: { bookingId }, order: { createdAt: 'DESC' } });
-  }
-
-  findAll(filter: Partial<Pick<WarehouseFeeInvoice, 'status' | 'invoiceType' | 'warehouseId' | 'facilityId' | 'customerId' | 'bookingId'>>): Promise<WarehouseFeeInvoice[]> {
-    const where = Object.fromEntries(Object.entries(filter).filter(([, v]) => v != null));
-    return this.invoiceRepository.findAll({ where, order: { createdAt: 'DESC' } });
-  }
-
-  // ── State changes ────────────────────────────────────────────────────────
-  async cancel(id: string): Promise<WarehouseFeeInvoice> {
-    const invoice = await this.invoiceRepository.findById(id);
-    if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
-    if (invoice.status === 'PAID') throw new BadRequestException('A paid invoice cannot be cancelled.');
-    const updated = await this.invoiceRepository.update(id, { status: 'CANCELLED', cancelledAt: new Date() });
-    return updated as WarehouseFeeInvoice;
-  }
-
-  /** Record a payment against the invoice and sync status (links to existing payment flow). */
-  async pay(id: string, dto: PayInvoiceDto): Promise<WarehouseFeeInvoice> {
-    const invoice = await this.invoiceRepository.findById(id);
-    if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
-    if (invoice.status === 'CANCELLED') throw new BadRequestException('Cannot pay a cancelled invoice.');
-    if (invoice.status === 'PAID') throw new BadRequestException('Invoice is already fully paid.');
-    if (!(dto.amount > 0)) throw new BadRequestException('Payment amount must be greater than zero.');
-
-    const { paidAmount, balanceAmount, fullyPaid } = applySettlement(
-      invoice.totalAmount,
-      invoice.paidAmount,
-      dto.amount,
-    );
-
-    const payments = [
-      ...(invoice.payments ?? []),
-      { amount: dto.amount, method: dto.method ?? null, reference: dto.reference ?? null, paidAt: new Date().toISOString() },
-    ];
-
-    const updated = await this.invoiceRepository.update(id, {
-      paidAmount,
-      balanceAmount,
-      status: fullyPaid ? 'PAID' : 'PARTIALLY_PAID',
-      paidAt: fullyPaid ? new Date() : invoice.paidAt ?? null,
-      payments,
-    });
-    const paidInvoice = updated as WarehouseFeeInvoice;
-    await this.notifyWarehouseFeePayment(paidInvoice, dto);
-    return paidInvoice;
-  }
-
-  // ── Release blocking ──────────────────────────────────────────────────────
-  /** Returns the first unpaid invoice that blocks terminal release, or null. */
-  async findBlockingInvoice(inventoryId: string): Promise<WarehouseFeeInvoice | null> {
-    const invoices = await this.invoiceRepository.findAll({ where: { inventoryId } });
-    return invoices.find((inv) => BLOCKING_STATUSES.includes(inv.status)) ?? null;
-  }
-
-  async assertClearanceAllowed(inventoryId: string): Promise<void> {
-    const invoices = await this.invoiceRepository.findAll({ where: { inventoryId } });
-    const blocking = invoices.find((inv) => BLOCKING_STATUSES.includes(inv.status));
-    if (blocking) {
-      throw new BadRequestException(
-        `Warehouse demurrage/storage invoice ${blocking.invoiceNumber} must be fully paid before terminal release.`,
-      );
-    }
-
-    if (invoices.some((inv) => inv.status === 'PAID')) return;
-
-    const previews = await this.feeService.previewForInventory(inventoryId, 'USD');
-    const payableAmount = previews.reduce((sum, fee) => sum + Number(fee.amount || 0), 0);
-    if (payableAmount > 0) {
-      throw new BadRequestException(
-        'Generate and fully pay the warehouse demurrage/storage invoice before terminal release.',
-      );
-    }
-  }
-
-  private async getInvoiceDocumentDetails(invoice: WarehouseFeeInvoice): Promise<InvoiceDocumentDetails> {
+  /** Warehouse-specific display details, derived from the linked inventory item. */
+  private async getInvoiceDocumentDetails(invoice: ViewSource): Promise<InvoiceDocumentDetails> {
     const [row] = await this.dataSource.query(
       `SELECT b.reference AS "bookingReference",
               company.name AS "customerName",
               COALESCE(inv.release_order_reference, b.reference) AS "inventoryReference",
               inv.status AS "inventoryStatus",
+              inv.release_date AS "releaseDate",
               COALESCE(container.container_number, booking_container.container_number) AS "containerNumber",
               COALESCE(cargo_type.cargo_type_name, b.cargo_free_text, cargo.description) AS "cargoDescription",
               CONCAT_WS(
@@ -355,16 +559,10 @@ export class WarehouseInvoiceService {
               ) AS "inventoryInfo",
               wh.name AS "warehouseName",
               yard.name AS "yardName",
-              zone.name AS "zoneName",
-              CASE
-                WHEN inv.release_date IS NOT NULL THEN 'RELEASE ISSUED'
-                WHEN $2 = 'PAID' THEN 'FEE PAID - READY FOR RELEASE'
-                ELSE 'PENDING PAYMENT'
-              END AS "clearanceStatus"
-         FROM freight.warehouse_fee_invoices fee
-         LEFT JOIN freight.warehouse_inventory inv ON inv.id = fee.inventory_id AND inv.deleted_at IS NULL
-         LEFT JOIN freight.bookings b ON b.id = fee.booking_id AND b.deleted_at IS NULL
-         LEFT JOIN freight.companies company ON company.id = COALESCE(fee.customer_id, b.company_id)
+              zone.name AS "zoneName"
+         FROM freight.warehouse_inventory inv
+         LEFT JOIN freight.bookings b ON b.id = inv.booking_id AND b.deleted_at IS NULL
+         LEFT JOIN freight.companies company ON company.id = b.company_id
          LEFT JOIN freight.containers container ON container.id = inv.container_id AND container.deleted_at IS NULL
          LEFT JOIN freight.booking_container booking_container ON (
            booking_container.booking_id = b.id
@@ -372,14 +570,21 @@ export class WarehouseInvoiceService {
          )
          LEFT JOIN freight.cargoes cargo ON cargo.id = inv.cargo_id AND cargo.deleted_at IS NULL
          LEFT JOIN freight.cargo_types cargo_type ON cargo_type.id = COALESCE(cargo.cargo_type_id, b.cargo_type_id)
-         LEFT JOIN freight.warehouses wh ON wh.id = fee.warehouse_id
-         LEFT JOIN freight.warehouse_yards yard ON yard.id = fee.yard_id
-         LEFT JOIN freight.warehouse_zones zone ON zone.id = fee.zone_id
-        WHERE fee.id = $1
+         LEFT JOIN freight.warehouses wh ON wh.id = inv.warehouse_id
+         LEFT JOIN freight.warehouse_yards yard ON yard.id = inv.yard_id
+         LEFT JOIN freight.warehouse_zones zone ON zone.id = inv.zone_id
+        WHERE inv.id = $1 AND inv.deleted_at IS NULL
         LIMIT 1`,
-      [invoice.id, invoice.status],
+      [invoice.sourceId],
     );
 
+    const fullyPaid = this.toWarehouseStatus(invoice.status) === 'PAID';
+    const clearanceStatus = row?.releaseDate
+      ? 'RELEASE ISSUED'
+      : fullyPaid
+        ? 'FEE PAID - READY FOR RELEASE'
+        : 'PENDING PAYMENT';
+
     return {
       bookingReference: row?.bookingReference ?? null,
       customerName: row?.customerName ?? null,
@@ -391,11 +596,33 @@ export class WarehouseInvoiceService {
       warehouseName: row?.warehouseName ?? null,
       yardName: row?.yardName ?? null,
       zoneName: row?.zoneName ?? null,
-      clearanceStatus: row?.clearanceStatus ?? (invoice.status === 'PAID' ? 'FEE PAID - READY FOR RELEASE' : 'PENDING PAYMENT'),
+      clearanceStatus,
     };
   }
 
-  private async getInvoiceNotificationContacts(invoice: WarehouseFeeInvoice): Promise<{
+  private async getInventoryContext(inventoryId: string): Promise<InventoryContext> {
+    const [row] = await this.dataSource.query(
+      `SELECT inv.booking_id AS "bookingId", inv.warehouse_id AS "warehouseId",
+              inv.yard_id AS "yardId", inv.zone_id AS "zoneId", inv.arrived_at AS "periodStart",
+              w.facility_id AS "facilityId"
+         FROM freight.warehouse_inventory inv
+         LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
+        WHERE inv.id = $1 AND inv.deleted_at IS NULL
+        LIMIT 1`,
+      [inventoryId],
+    );
+    return {
+      bookingId: row?.bookingId ?? null,
+      facilityId: row?.facilityId ?? null,
+      warehouseId: row?.warehouseId ?? null,
+      yardId: row?.yardId ?? null,
+      zoneId: row?.zoneId ?? null,
+      periodStart: row?.periodStart ?? null,
+    };
+  }
+
+  // ── Notifications ──────────────────────────────────────────────────────────
+  private async getInvoiceNotificationContacts(inventoryId: string): Promise<{
     bookingReference: string | null;
     customerName: string | null;
     customerPhone: string | null;
@@ -417,10 +644,9 @@ export class WarehouseInvoiceService {
               COALESCE(last_driver.phone_number, first_driver.phone_number) AS "driverPhone",
               COALESCE(container.container_number, booking_container.container_number) AS "containerNumber",
               COALESCE(cargo_type.cargo_type_name, b.cargo_free_text, cargo.description) AS "cargoDescription"
-         FROM freight.warehouse_fee_invoices fee
-         LEFT JOIN freight.warehouse_inventory inv ON inv.id = fee.inventory_id AND inv.deleted_at IS NULL
-         LEFT JOIN freight.bookings b ON b.id = fee.booking_id AND b.deleted_at IS NULL
-         LEFT JOIN freight.companies company ON company.id = COALESCE(fee.customer_id, b.company_id)
+         FROM freight.warehouse_inventory inv
+         LEFT JOIN freight.bookings b ON b.id = inv.booking_id AND b.deleted_at IS NULL
+         LEFT JOIN freight.companies company ON company.id = b.company_id
          LEFT JOIN freight.containers container ON container.id = inv.container_id AND container.deleted_at IS NULL
          LEFT JOIN freight.booking_container booking_container ON (
            booking_container.booking_id = b.id
@@ -446,9 +672,9 @@ export class WarehouseInvoiceService {
          ) latest_first_mile ON true
          LEFT JOIN freight.vehicles first_vehicle ON first_vehicle.id = latest_first_mile.vehicle_id
          LEFT JOIN freight.drivers first_driver ON first_driver.id = first_vehicle.assigned_driver_id
-        WHERE fee.id = $1
+        WHERE inv.id = $1 AND inv.deleted_at IS NULL
         LIMIT 1`,
-      [invoice.id],
+      [inventoryId],
     );
 
     return {
@@ -472,8 +698,8 @@ export class WarehouseInvoiceService {
     }
   }
 
-  private async notifyWarehouseFeeIssued(invoice: WarehouseFeeInvoice): Promise<void> {
-    const contacts = await this.getInvoiceNotificationContacts(invoice);
+  private async notifyWarehouseFeeIssued(invoice: WarehouseFeeInvoiceView): Promise<void> {
+    const contacts = await this.getInvoiceNotificationContacts(invoice.inventoryId);
     const customerName = contacts.customerName?.trim() || 'Customer';
     const bookingReference = contacts.bookingReference ? ` Booking: ${contacts.bookingReference}.` : '';
     const cargo = contacts.containerNumber || contacts.cargoDescription;
@@ -486,8 +712,8 @@ export class WarehouseInvoiceService {
     await this.sendSms(contacts.customerPhone, message, `warehouse fee invoice ${invoice.invoiceNumber}`);
   }
 
-  private async notifyWarehouseFeePayment(invoice: WarehouseFeeInvoice, dto: PayInvoiceDto): Promise<void> {
-    const contacts = await this.getInvoiceNotificationContacts(invoice);
+  private async notifyWarehouseFeePayment(invoice: WarehouseFeeInvoiceView, dto: PayInvoiceDto): Promise<void> {
+    const contacts = await this.getInvoiceNotificationContacts(invoice.inventoryId);
     const customerName = contacts.customerName?.trim() || 'Customer';
     const bookingReference = contacts.bookingReference ? ` Booking: ${contacts.bookingReference}.` : '';
     const statusText =
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.types.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.types.ts
new file mode 100644
index 000000000..e201241ba
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.types.ts
@@ -0,0 +1,88 @@
+/**
+ * Public shapes for warehouse fee invoices.
+ *
+ * Warehouse fee invoices are no longer a standalone table — they are global
+ * `Invoice` rows (`source = "warehouse"`, `sourceId = inventoryId`) owned by the
+ * central {@link BillingService}. These types preserve the warehouse-facing API
+ * contract: `WarehouseInvoiceService` reshapes the global invoice (+ lines +
+ * inventory context) back into the historical `WarehouseFeeInvoice` JSON so the
+ * portal/backoffice stay untouched.
+ */
+
+export const WAREHOUSE_INVOICE_TYPES = ['DEMURRAGE', 'STORAGE_FEE', 'MIXED_WAREHOUSE_FEES'] as const;
+export type WarehouseInvoiceType = (typeof WAREHOUSE_INVOICE_TYPES)[number];
+
+export const WAREHOUSE_INVOICE_STATUSES = [
+  'DRAFT',
+  'ISSUED',
+  'PARTIALLY_PAID',
+  'PAID',
+  'CANCELLED',
+] as const;
+export type WarehouseInvoiceStatus = (typeof WAREHOUSE_INVOICE_STATUSES)[number];
+
+export const WAREHOUSE_FEE_TYPES = [
+  'CONTAINER_DEMURRAGE',
+  'BULK_DEMURRAGE',
+  'STORAGE_FEE',
+  'HANDLING_FEE',
+] as const;
+export type WarehouseFeeType = (typeof WAREHOUSE_FEE_TYPES)[number];
+
+/** A single recorded payment against a warehouse fee invoice (history). */
+export interface WarehouseInvoicePayment {
+  amount: number;
+  method?: string | null;
+  reference?: string | null;
+  paidAt: string;
+}
+
+/** A billed warehouse fee line, projected from a global `InvoiceLine`. */
+export interface WarehouseInvoiceItemView {
+  feeRuleId: string | null;
+  feeType: WarehouseFeeType;
+  description: string;
+  quantity: number;
+  unitRate: number;
+  amount: number;
+  currency: string;
+  chargeableDays: number | null;
+  freeDays: number | null;
+}
+
+/**
+ * The warehouse-facing invoice header — same field set the old
+ * `WarehouseFeeInvoice` entity exposed, projected from a global `Invoice`. The
+ * typed FKs (`bookingId`/`facilityId`/`warehouseId`/`yardId`/`zoneId`) and the
+ * charge `period` are derived from the linked inventory item; `customerId` is the
+ * billed company; `invoiceType` is the invoice `type`.
+ */
+export interface WarehouseFeeInvoiceView {
+  id: string;
+  invoiceNumber: string;
+  bookingId: string | null;
+  customerId: string | null;
+  inventoryId: string;
+  facilityId: string | null;
+  warehouseId: string | null;
+  yardId: string | null;
+  zoneId: string | null;
+  invoiceType: WarehouseInvoiceType;
+  status: WarehouseInvoiceStatus;
+  subtotalAmount: number;
+  taxAmount: number;
+  totalAmount: number;
+  paidAmount: number;
+  balanceAmount: number;
+  currency: string;
+  periodStart: Date | null;
+  periodEnd: Date | null;
+  issuedAt: Date | null;
+  dueDate: Date | null;
+  paidAt: Date | null;
+  cancelledAt: Date | null;
+  payments: WarehouseInvoicePayment[];
+  notes: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts b/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
index a7ce68319..b871d2a36 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouses.module.ts
@@ -3,6 +3,7 @@ import { ConfigService } from '@nestjs/config';
 import { ExchangeModule, ExchangeOptions } from '@edr/api-common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { BillingModule } from '../billing/billing.module';
 import { DocumentsModule } from '../billing/documents/documents.module';
 import { FilesModule } from '../files/files.module';
 import { InterchangeDocumentsModule } from '../interchange-documents/interchange-documents.module';
@@ -11,8 +12,6 @@ import { NotificationsModule } from '../notifications/notifications.module';
 import { SignaturesModule } from '../signatures/signatures.module';
 import { WarehouseActivityLog } from './entities/warehouse-activity-log.entity';
 import { WarehouseAllocationRule } from './entities/warehouse-allocation-rule.entity';
-import { WarehouseFeeInvoice } from './entities/warehouse-fee-invoice.entity';
-import { WarehouseFeeInvoiceItem } from './entities/warehouse-fee-invoice-item.entity';
 import { WarehouseFeeRule } from './entities/warehouse-fee-rule.entity';
 import { WarehouseInspectionReport } from './entities/warehouse-inspection-report.entity';
 import { WarehouseInventory } from './entities/warehouse-inventory.entity';
@@ -39,8 +38,6 @@ import { WarehouseAllocationRuleRepository } from './warehouse-allocation-rule.r
 import { WarehouseAllocationService } from './warehouse-allocation.service';
 import { WarehouseFeeRuleRepository } from './warehouse-fee-rule.repository';
 import { WarehouseFeeService } from './warehouse-fee.service';
-import { WarehouseFeeInvoiceItemRepository } from './warehouse-fee-invoice-item.repository';
-import { WarehouseFeeInvoiceRepository } from './warehouse-fee-invoice.repository';
 import { WarehouseInvoiceController } from './warehouse-invoice.controller';
 import { WarehouseInvoiceService } from './warehouse-invoice.service';
 import { WarehouseRulesController } from './warehouse-rules.controller';
@@ -68,9 +65,8 @@ import { WarehousesService } from './warehouses.service';
       WarehouseInspectionReport,
       WarehouseAllocationRule,
       WarehouseFeeRule,
-      WarehouseFeeInvoice,
-      WarehouseFeeInvoiceItem,
     ]),
+    BillingModule,
     DocumentsModule,
     FilesModule,
     InterchangeDocumentsModule,
@@ -104,8 +100,6 @@ import { WarehousesService } from './warehouses.service';
     WarehouseInspectionRepository,
     WarehouseAllocationRuleRepository,
     WarehouseFeeRuleRepository,
-    WarehouseFeeInvoiceRepository,
-    WarehouseFeeInvoiceItemRepository,
     WarehousesService,
     WarehouseYardsService,
     WarehouseZonesService,
diff --git a/apps/edr-freight-api/tsconfig.json b/apps/edr-freight-api/tsconfig.json
index 467c474ee..52598cb95 100644
--- a/apps/edr-freight-api/tsconfig.json
+++ b/apps/edr-freight-api/tsconfig.json
@@ -7,6 +7,7 @@
     "noEmit": false,
     "incremental": true,
     "tsBuildInfoFile": "./.tsbuildinfo",
+    "preserveWatchOutput": true,
     "module": "node16",
     "moduleResolution": "node16"
   },

From 0056dec9248f73ce820b1de3cf54d74ec817a549 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 30 Jun 2026 13:28:14 +0000
Subject: [PATCH 59/63] style: clean up the invoice and setup event for
 warehouse.

---
 .../modules/billing/billing.service.spec.ts   |  2 +-
 .../src/modules/billing/billing.service.ts    | 16 +++----
 .../src/modules/payment/payment.controller.ts | 13 +-----
 .../src/modules/payment/payment.service.ts    | 46 ++-----------------
 .../warehouses/warehouse-invoice.service.ts   | 21 +++++++--
 5 files changed, 30 insertions(+), 68 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index e52dfafa1..61597264b 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -89,7 +89,7 @@ describe("BillingService.generateInvoice", () => {
     expect(invoice.sourceId).toBe("booking-1");
     expect(invoice.totalAmount).toBe(1500);
     expect(invoice.issuedAt).toBeInstanceOf(Date);
-    expect(invoice.invoiceNumber).toMatch(/^FRT-\d{8}-00001$/);
+    expect(invoice.invoiceNumber).toMatch(/^INV-\d{8}-00001$/);
     expect(savedLines).toHaveLength(2);
   });
 
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index e4389e7cf..f1b58ad5e 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -96,11 +96,6 @@ export interface GenerateInvoiceInput {
    * (default PENDING) stamps `issuedAt`.
    */
   status?: Freight.InvoiceStatus;
-  /**
-   * Document number prefix for this source (e.g. `WHF` for warehouse fees);
-   * defaults to `FRT`. The daily sequence is allocated per prefix.
-   */
-  numberCode?: string;
 }
 
 /** Payload broadcast on `${source}.invoice.<event>`. */
@@ -665,11 +660,12 @@ export class BillingService {
     const result = await this.payment.initiate({
       referenceId: sourceId,
       source: invoice.source,
-      // Gateway reference type derives from the invoice source by convention
-      // (source.toUpperCase() ∈ PaymentReferenceType) — no domain word here, and
-      // the domain never supplies it. New sources add their uppercased value to
-      // the PaymentReferenceType enum.
-      referenceType: invoice.source.toUpperCase() as PaymentReferenceType,
+      // Freight payments settle under the generic SHIPMENT reference — how the
+      // payment service attributes them to the freight API. The payment ↔ invoice
+      // link is the intent id (`paymentId`); per-source post-payment reactions live
+      // in the domain via `${source}.invoice.paid`. Neither billing nor the payment
+      // service branches on a domain-specific reference type.
+      referenceType: PaymentReferenceType.SHIPMENT,
       orderRef: invoice.invoiceNumber,
       amountMinor: Math.round(Number(invoice.totalAmount)),
       currency: invoice.currency,
diff --git a/apps/edr-freight-api/src/modules/payment/payment.controller.ts b/apps/edr-freight-api/src/modules/payment/payment.controller.ts
index b1b269665..50856c3d7 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.controller.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.controller.ts
@@ -6,8 +6,6 @@ import {
     ParseUUIDPipe,
     Query,
     Res,
-    Body,
-    Post,
 } from "@nestjs/common";
 import {
     ApiTags,
@@ -18,9 +16,9 @@ import {
 } from "@nestjs/swagger";
 import { Response } from "express";
 import { Public } from "@edr/api-common";
-import { BookingView, FreightAdmin } from "../../common/booking-guards";
+import { BookingView } from "../../common/booking-guards";
 import { PaymentService } from "./payment.service";
-import { IntentStatusDto, RefundDto } from "./payments.dto";
+import { IntentStatusDto } from "./payments.dto";
 
 @ApiTags("Payment")
 @Controller("payments")
@@ -73,13 +71,6 @@ export class PaymentController {
         return this.paymentService.getIntentByBookingId(bookingId);
     }
 
-    @Post("refund")
-    @FreightAdmin()
-    @ApiOperation({ summary: "Refund a paid booking (staff/admin only)" })
-    refund(@Body() dto: RefundDto) {
-        return this.paymentService.refund(dto);
-    }
-
     @Get("receipt/:orderId")
     @Public()
     @ApiOperation({ summary: "Generate a payment receipt HTML page" })
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 738a6d118..d92af7a3e 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -7,7 +7,6 @@ import {
   Logger,
   NotFoundException,
 } from "@nestjs/common";
-import { DataSource } from "typeorm";
 import { PaymentEntity } from "./entities/payment.entity";
 import { PaymentRepository } from "./payment.repository";
 import { PaymentClientService } from "./payment-client.service";
@@ -16,7 +15,6 @@ import { BillingService } from "../billing/billing.service";
 import * as fs from "fs";
 import * as path from "path";
 import * as Handlebars from "handlebars";
-import { Booking } from "../bookings/entities/booking.entity";
 
 import { ClientAction, ProviderPaymentStatus } from "@edr/payment-providers";
 import {
@@ -29,7 +27,6 @@ import {
   InitiateResponseDto,
   IntentStatusDto,
   PaymentPlatformDto,
-  RefundDto,
 } from "./payments.dto";
 
 /** Everything the gateway needs to open an intent. Amount/currency are supplied by
@@ -96,7 +93,6 @@ export class PaymentService {
   private readonly logger = new Logger(PaymentService.name);
 
   constructor(
-    private readonly datasource: DataSource,
     private readonly paymentRepo: PaymentRepository,
     private readonly paymentClient: PaymentClientService,
     @Inject(forwardRef(() => BillingService))
@@ -404,34 +400,6 @@ export class PaymentService {
     );
   }
 
-  async refund(dto: RefundDto) {
-    const intent = await this.paymentRepo.findOneBy({
-      refId: dto.bookingId,
-      type: "booking",
-    });
-    if (!intent || intent.status !== "success") {
-      throw new BadRequestException("No successful payment to refund");
-    }
-
-    // NOTE: refunding still mutates the booking directly — left intact pending
-    // the refund redesign. TODO: route refunds through billing.refundPayable +
-    // a `${source}.invoice.refunded` reaction, like settlement.
-    await this.datasource.transaction(async (mg) => {
-      await mg.update(
-        PaymentEntity,
-        { id: intent.id },
-        { status: "refunded", refundedAt: new Date() },
-      );
-      await mg.update(
-        Booking,
-        { id: dto.bookingId },
-        { paymentStatus: "FAILED", status: "CANCELLED" },
-      );
-    });
-
-    return { refunded: true, bookingId: dto.bookingId };
-  }
-
   async getActivePaymentByOrderIdAndMethod(
     orderId: string,
     method: PaymentEntity["method"],
@@ -527,16 +495,10 @@ export class PaymentService {
         `Payment finalized for intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`,
       );
 
-      // When the intent references a booking, flip the booking itself paid.
-      // refId holds the booking id (the domain reference the intent opened with).
-      if (intent.referenceType === PaymentReferenceType.BOOKING) {
-        await this.datasource.manager.update(
-          Booking,
-          { id: intent.refId },
-          { status: "PAID", paymentStatus: "PAID" },
-        );
-      }
-      // console.log(`Payment finalized for booking ${event.referenceId}, intent ${intent.id}, alreadyFinalized: ${alreadyFinalized}`);
+      // The payment service stays domain-agnostic: it settles the intent and
+      // lets billing settle the invoice (markIntentSucceeded → settleByPaymentId),
+      // which emits `${source}.invoice.paid`. Per-source advances (booking → PAID,
+      // warehouse → release, …) live in the domain services that listen for it.
       return { processed: true, alreadyFinalized };
     }
 
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
index 9b349181d..6f7219781 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
@@ -1,8 +1,9 @@
 import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
 import { Freight } from '@edr/types';
 import { DataSource } from 'typeorm';
 
-import { BillingService, InvoiceLineInput } from '../billing/billing.service';
+import { BillingService, InvoiceEventPayload, InvoiceLineInput } from '../billing/billing.service';
 import { Invoice } from '../billing/entities/invoice.entity';
 import { InvoiceLine } from '../billing/entities/invoice-line.entity';
 import {
@@ -35,8 +36,6 @@ export interface PayInvoiceDto {
 
 /** Warehouse fee invoices live in the global billing system under this source. */
 const SOURCE = Freight.InvoiceSource.Warehouse;
-/** Document number prefix kept for warehouse fee invoices (e.g. `WHF-20260630-00001`). */
-const NUMBER_CODE = 'WHF';
 
 /** Global statuses that still owe money and therefore block terminal release. */
 const BLOCKING_STATUSES: Freight.InvoiceStatus[] = [
@@ -216,7 +215,6 @@ export class WarehouseInvoiceService {
       currency: billingCurrency,
       lines,
       status: Freight.InvoiceStatus.Issued,
-      numberCode: NUMBER_CODE,
     });
 
     const detail = await this.findById(invoice.id);
@@ -307,6 +305,21 @@ export class WarehouseInvoiceService {
     return detail;
   }
 
+  /**
+   * Notify on online (gateway) settlement — the domain side-effect of a warehouse
+   * fee being paid through billing's payment flow. The counter {@link pay} path
+   * notifies inline (and carries driver details from the request), so this only
+   * handles gateway payments: those stamp the invoice `paymentId`, whereas a
+   * counter settlement leaves it null. Skipping null-`paymentId` events avoids
+   * double-notifying a counter payment that already sent its SMS.
+   */
+  @OnEvent('warehouse.invoice.paid')
+  async onWarehouseInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
+    if (!payload.paymentId) return;
+    const detail = await this.findById(payload.invoiceId);
+    await this.notifyWarehouseFeePayment(detail, { amount: Number(detail.totalAmount) });
+  }
+
   // ── Release blocking ──────────────────────────────────────────────────────
   /** Returns the first unpaid invoice that blocks terminal release, or null. */
   async findBlockingInvoice(inventoryId: string): Promise<WarehouseFeeInvoiceView | null> {

From 156747f42fc05688634bf73182a5e3c7e073cddd Mon Sep 17 00:00:00 2001
From: hagiye <hageritina27@gmail.com>
Date: Tue, 30 Jun 2026 16:48:08 +0300
Subject: [PATCH 60/63] Approve delivery button for customer to sign or
 acknowlegde delivery

---
 apps/edr-freight-web/backoffice/src/constants/apiConfig.ts | 5 ++---
 apps/edr-freight-web/portal/src/constants/apiConfig.ts     | 4 ++--
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index a60559d5d..07496364b 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,6 +1,5 @@
-//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-
-export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+//export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index b2d93ca3a..59324b76f 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,5 +1,5 @@
-//export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
-export const API_BASE_URL = 'http://localhost:3001';
+export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
+//export const API_BASE_URL = 'http://localhost:3001';
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the

From 38db9a4177a40af201f7f79f1d93f6381b7f5305 Mon Sep 17 00:00:00 2001
From: hagiye <hageritina27@gmail.com>
Date: Tue, 30 Jun 2026 17:05:53 +0300
Subject: [PATCH 61/63] Delivery approval customer handover signature

---
 .../edr-freight-web/backoffice/src/constants/apiConfig.ts | 8 ++++----
 apps/edr-freight-web/portal/src/constants/apiConfig.ts    | 4 ----
 2 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
index 0a5ce4647..07e271cb6 100644
--- a/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/apiConfig.ts
@@ -1,11 +1,11 @@
-<<<<<<< HEAD
+
 export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
 //export const API_BASE_URL = 'http://localhost:3001';
-=======
-export const API_BASE_URL = import.meta.env.VITE_BASE_API_URL;
+
+
 
 // export const API_BASE_URL = 'http://localhost:3001';
->>>>>>> 8616f6dcdfa44089be2fd7b6a9867b20e320b305
+
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the
diff --git a/apps/edr-freight-web/portal/src/constants/apiConfig.ts b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
index c51eb9e7b..07496364b 100644
--- a/apps/edr-freight-web/portal/src/constants/apiConfig.ts
+++ b/apps/edr-freight-web/portal/src/constants/apiConfig.ts
@@ -1,9 +1,5 @@
-<<<<<<< HEAD
 export const API_BASE_URL = 'https://edrfreightapi.triaplc.com';
 //export const API_BASE_URL = 'http://localhost:3001';
-=======
-export const API_BASE_URL = import.meta.env.VITE_BASE_API_URL;
->>>>>>> 8616f6dcdfa44089be2fd7b6a9867b20e320b305
 
 /**
  * URL that streams an uploaded file through the API by its UUID. Routes the

From 1c9efed1031fd4658ccab5b3815f059350935499 Mon Sep 17 00:00:00 2001
From: Abubeker Yasin <dev.abubeker@gmail.com>
Date: Tue, 30 Jun 2026 20:06:43 +0300
Subject: [PATCH 62/63] fix: ( payment ) add ispublic to payment event consumer

---
 apps/edr-passenger-api/src/common/dynamic-throttler.guard.ts  | 4 ++++
 .../src/modules/payments/payment-events.consumer.ts           | 2 ++
 .../payment-providers/src/providers/dmoney/dmoney.provider.ts | 3 +++
 3 files changed, 9 insertions(+)

diff --git a/apps/edr-passenger-api/src/common/dynamic-throttler.guard.ts b/apps/edr-passenger-api/src/common/dynamic-throttler.guard.ts
index 43ddecddf..7a450bfaf 100644
--- a/apps/edr-passenger-api/src/common/dynamic-throttler.guard.ts
+++ b/apps/edr-passenger-api/src/common/dynamic-throttler.guard.ts
@@ -15,6 +15,10 @@ export class DynamicThrottlerGuard extends ThrottlerGuard {
   }
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
+    if (context.getType() !== 'http') {
+      return true;
+    }
+
     const [authLimit, authTtl, strictLimit, strictTtl, defaultLimit, defaultTtl] =
       await Promise.all([
         this.systemConfig.getNumber(CONFIG_KEYS.THROTTLE_AUTH_LIMIT),
diff --git a/apps/edr-passenger-api/src/modules/payments/payment-events.consumer.ts b/apps/edr-passenger-api/src/modules/payments/payment-events.consumer.ts
index f13191c48..a80c63468 100644
--- a/apps/edr-passenger-api/src/modules/payments/payment-events.consumer.ts
+++ b/apps/edr-passenger-api/src/modules/payments/payment-events.consumer.ts
@@ -1,5 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { Nack, RabbitSubscribe } from '@golevelup/nestjs-rabbitmq';
+import { IsPublic } from '@tria-plc/api-common/modules/auth/decorators/public.decorator';
 import {
   PAYMENT_EVENTS_DLX,
   PAYMENT_EVENTS_EXCHANGE,
@@ -19,6 +20,7 @@ export class PaymentEventsConsumer {
 
   constructor(private readonly paymentsService: PaymentsService) {}
 
+  @IsPublic()
   @RabbitSubscribe({
     exchange: PAYMENT_EVENTS_EXCHANGE,
     routingKey: paymentServiceBindingPattern(PaymentService.PASSENGER), // payment.passenger.*
diff --git a/packages/payment-providers/src/providers/dmoney/dmoney.provider.ts b/packages/payment-providers/src/providers/dmoney/dmoney.provider.ts
index 32b41dbb1..15a2e3a62 100644
--- a/packages/payment-providers/src/providers/dmoney/dmoney.provider.ts
+++ b/packages/payment-providers/src/providers/dmoney/dmoney.provider.ts
@@ -61,6 +61,9 @@ export class DMoneyProvider implements PaymentProvider {
   ): Promise<ProviderInitiationResult> {
     const fabricToken = await this.applyFabricToken();
     const requestBody = this.buildPreOrderRequest(input);
+    this.logger.log(
+      `D-Money preOrder send request merchOrderId=${input.merchantOrderId} body=${JSON.stringify(this.sanitize(requestBody))}`,
+    );
     const response = await this.postJson<DMoneyPreOrderResponse>(
       `${this.baseUrl}/apiaccess/payment/gateway/payment/v1/merchant/preOrder`,
       requestBody,

From 8a7799be0e3fabbc06fdb7c8bc1a193f1b89df1b Mon Sep 17 00:00:00 2001
From: Roba Boru <robab@ethiopianairines.com>
Date: Wed, 1 Jul 2026 08:00:47 +0300
Subject: [PATCH 63/63] Added callback url for fayda

---
 .../src/app/booking/passengers/page.tsx       | 56 ++++++++++++++++++-
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx b/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
index b38234732..4b46859d6 100644
--- a/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
+++ b/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
@@ -512,6 +512,8 @@ export default function PassengersPage() {
   const [verificationStatus, setVerificationStatus] = useState<Record<number, 'success' | 'error'>>({});
   const [saving, setSaving] = useState(false);
   const [formInitialized, setFormInitialized] = useState(false);
+  const [faydaParams, setFaydaParams] = useState<{ code: string; state: string } | null>(null);
+  const [faydaCompleting, setFaydaCompleting] = useState(false);
 
 
   const totalPassengers = (searchCriteria?.adultCount || 1) + (searchCriteria?.childCount || 0);
@@ -576,6 +578,54 @@ export default function PassengersPage() {
     checkFaydaStatus();
   }, []);
 
+  // Read Fayda callback params from the URL on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get('code');
+    const state = params.get('state');
+    if (code && state) setFaydaParams({ code, state });
+  }, []);
+
+  // Complete Fayda verification once the form is ready and callback params are present
+  useEffect(() => {
+    if (!faydaParams || !formInitialized) return;
+
+    const complete = async () => {
+      setFaydaCompleting(true);
+      try {
+        const response: any = await apiClient.get(
+          `/fayda/verification/complete?code=${encodeURIComponent(faydaParams.code)}&state=${encodeURIComponent(faydaParams.state)}`
+        );
+
+        if (response?.success && response?.data?.verified) {
+          const d = response.data;
+          // Convert "1980/12/01" → "1980-12-01"
+          const dob = d.birthdate ? (d.birthdate as string).replace(/\//g, '-') : '';
+
+          setValue('passengers.0.name', d.fullName || '', { shouldValidate: true });
+          if (dob) setValue('passengers.0.dateOfBirth', dob, { shouldValidate: true });
+          if (d.email) setValue('passengers.0.email', d.email, { shouldValidate: true });
+          if (d.phoneNumber) setValue('passengers.0.phone', d.phoneNumber, { shouldValidate: true });
+          setValue('passengers.0.faydaVerified', true);
+          setValue('passengers.0.formExpanded', true);
+          setVerificationStatus((prev) => ({ ...prev, 0: 'success' }));
+
+          // Remove code/state from the URL so a refresh doesn't re-trigger
+          router.replace('/booking/passengers');
+        }
+      } catch (error) {
+        console.error('Failed to complete Fayda verification:', error);
+      } finally {
+        setFaydaCompleting(false);
+        setFaydaParams(null);
+      }
+    };
+
+    complete();
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [faydaParams, formInitialized]);
+
   useEffect(() => {
     if (isAuthenticated && user?.faydaVerified) {
       setVerificationStatus({ 0: 'success' });
@@ -752,13 +802,15 @@ export default function PassengersPage() {
 
   if (!searchCriteria) return null;
 
-  if (!formInitialized) {
+  if (!formInitialized || faydaCompleting) {
     return (
       <div className="min-h-screen bg-gray-50 dark:bg-gray-900 py-12">
         <div className="container mx-auto px-4">
           <div className="max-w-lg mx-auto text-center">
             <Loader2 className="w-8 h-8 animate-spin mx-auto text-blue-600" />
-            <p className="text-gray-600 dark:text-gray-400 mt-4">Loading passenger details...</p>
+            <p className="text-gray-600 dark:text-gray-400 mt-4">
+              {faydaCompleting ? 'Completing Fayda verification...' : 'Loading passenger details...'}
+            </p>
           </div>
         </div>
       </div>