ERPNext Core Integration

Logistics ↔ ERPNext Core Integration: Current Status & Proposed Design

Date: February 14, 2026
Scope: Cost and revenue flows from logistics jobs/shipments to ERPNext Purchase and Sales modules; invoicing and payment monitoring
Purpose: Document current state and propose a unified design for cost → Purchase Invoice (or PR/PO) and revenue → Sales Invoice, plus full invoicing/payment status tracking

---

1. Executive Summary

Flow	Current State	Proposed
Revenue → Sales Invoice	✅ Implemented for Transport Job, Air Shipment, Sea Shipment, Warehouse Job, Declaration, Periodic Billing	Enhance with reference linkage and monitoring fields
Costs → Purchase Invoice	❌ Not implemented	Add create_purchase_invoice from job/shipment costs
Costs → Purchase Request/Order	❌ Not implemented	Add optional flow via module settings
Fully Invoiced / Fully Paid	⚠️ Partial (billing_status only)	Add standardized monitoring fields and dates

---

2. Current Status

2.1 Revenue → Sales Invoice (Implemented)

Source DocType	Method	Link Field	Notes
Transport Job	create_sales_invoice(job_name)	sales_invoice	Charges → SI items; auto-trigger on status=Completed
Air Shipment	create_sales_invoice()	sales_invoice	Charges → SI items; filter by bill_to, invoice_type
Sea Shipment	create_sales_invoice(shipment_name, posting_date, customer, …)	—	Charges → SI items; filter by bill_to, invoice_type
Warehouse Job	create_sales_invoice_from_job()	—	Charges → SI items; via ops.py
Declaration	create_sales_invoice(declaration_name)	—	Charges → SI items
Periodic Billing	create_sales_invoice_from_periodic_billing()	sales_invoice	PB charges → SI items

Gaps:

• Sea Shipment and some others do not consistently set sales_invoice back-reference on the source document.
• Sales Invoice Item does not receive reference_doctype / reference_name when created from jobs — the Recognition Engine’s calculate_actual_revenue_as_of() expects these on SI Item but they are not populated.
• No standardized “fully invoiced” or “fully paid” flags or dates at job/shipment level.

2.2 Costs → Purchase Invoice (Not Implemented)

Aspect	Status
Create Purchase Invoice from job/shipment costs	❌ No function exists
Link Purchase Invoice back to job/shipment	❌ No purchase_invoice field on jobs/shipments
Purchase Invoice Item reference to job	Recognition Engine expects reference_doctype / reference_name on PI Item; standard PI Item has no such fields

Recognition Engine (existing):

• calculate_actual_costs_as_of() queries Purchase Invoice Item with reference_doctype = job type and reference_name = job name.
• These fields are not present on standard ERPNext Purchase Invoice Item.
• Cost recognition today is via Journal Entry (accrual) only, not via Purchase Invoice.

2.3 Costs → Purchase Request / Purchase Order (Not Implemented)

Aspect	Status
Create Purchase Request from costs	❌ Not implemented
Create Purchase Order from costs	❌ Not implemented
Module setting “costs require purchasing process”	❌ No such setting exists

2.4 Charge Schemas (Cost vs Revenue)

DocType	Revenue Fields	Cost Fields	Supplier
Transport Job Charges	unit_rate, estimated_revenue	unit_cost, estimated_cost	—
Air Shipment Charges	estimated_revenue, total_amount	estimated_cost	—
Sea Freight Charges	selling_amount, bill_to	buying_amount, pay_to (Supplier)	pay_to
Warehouse Job Charges	(billing via contract)	total_standard_cost	—
Declaration Charges	—	—	—

Sea Freight Charges is the only schema with an explicit pay_to (Supplier) link; others have cost amounts but no supplier.

2.5 Invoicing and Payment Monitoring

DocType	Fields	Values
Air Shipment	billing_status, billing_amount, billing_date, sales_invoice	Not Billed, Pending, Billed, Partially Billed, Overdue, Cancelled
Sea Shipment	billing_status	Similar
Air Shipment Charges	billing_status, payment_status	Pending, Billed, Paid, Overdue, Cancelled
Air/Sea Consolidation Charges	billing_status, payment_status	Same
Declaration	payment_status	—
Transport Job	sales_invoice only	No billing_status
Warehouse Job	—	No billing_status

Missing:

• fully_invoiced (Check)
• fully_paid (Check)
• date_fully_invoiced (Date)
• date_fully_paid (Date)
• Consistent purchase_invoice link for cost tracking

---

3. Proposed Design

3.1 Standard Fields for Job/Shipment DocTypes

Add to Transport Job, Air Shipment, Sea Shipment, Warehouse Job, Declaration (and optionally General Job):

Field	Type	Label	Description
sales_invoice	Link → Sales Invoice	Sales Invoice	Already exists on some; add where missing
purchase_invoice	Link → Purchase Invoice	Purchase Invoice	Primary PI for costs (or first if multiple)
fully_invoiced	Check	Fully Invoiced	Revenue fully billed
date_fully_invoiced	Date	Date Fully Invoiced	When revenue was fully invoiced
fully_paid	Check	Fully Paid	All receivables paid
date_fully_paid	Date	Date Fully Paid	When fully paid

Child / charge-level (where applicable):

• purchase_invoice on charge rows for cost items that have been invoiced by supplier.

3.2 Cost Flow: Create Purchase Invoice

New function: create_purchase_invoice(job_type, job_name, supplier=None, posting_date=None)

Logic:

1. Load job (Transport Job, Air Shipment, Sea Shipment, etc.).
2. Filter charges with cost amount > 0 and (where applicable) pay_to (supplier).
3. For each charge:
   • If pay_to exists → use as supplier for that line (or group by supplier).
   • If no supplier → use default supplier from module settings or company.
4. Create Purchase Invoice with:
   • supplier from charge or default
   • Items from charges (item_code, qty, rate = cost amount)
   • reference_type = job type, reference_name = job name (on PI header)
5. Add custom fields to Purchase Invoice and Purchase Invoice Item:
   • PI: reference_doctype, reference_name (or use standard reference_type/reference_name if available)
   • PI Item: reference_doctype, reference_name (for Recognition Engine)
6. Set purchase_invoice on job.
7. Support multiple PIs per job when costs are split by supplier.

Module setting (per module):

• require_purchasing_process (Check): If enabled, costs must go through Purchase Request → Purchase Order → Purchase Invoice instead of direct PI.

3.3 Cost Flow: Purchase Request / Purchase Order (Optional)

When require_purchasing_process is enabled:

1. Create Purchase Request from job costs:

   • One PR per job (or per supplier) with items from charges.
   • Link PR to job via reference_doctype / reference_name.

2. Create Purchase Order from PR (standard ERPNext flow).

3. Create Purchase Invoice from PO (standard ERPNext flow).

4. On PI creation/submit:

   • Set purchase_invoice on job (or append to list if multiple).
   • Update fully_invoiced for costs when all cost charges are covered by PI(s).

3.4 Revenue Flow: Enhancements

1. Set reference_doctype / reference_name on Sales Invoice Item when creating SI from job:

   • Ensures Recognition Engine’s calculate_actual_revenue_as_of() works.
   • Add custom fields to Sales Invoice Item if not present.

2. Set sales_invoice on source for all modules (Sea Shipment, Declaration, Warehouse Job where missing).

3. Update fully_invoiced and date_fully_invoiced:

   • On SI submit: compare sum of SI amounts vs total revenue from charges.
   • If equal (within tolerance) → fully_invoiced = 1, date_fully_invoiced = SI posting_date.

3.5 Payment Monitoring

1. fully_paid and date_fully_paid:

   • Update via hook on Payment Entry (or similar) when linked Sales Invoice is fully allocated.
   • Or: scheduled job that checks outstanding_amount of linked SI; when 0 → set fully_paid = 1, date_fully_paid = today.

2. Payment status for costs (optional):

   • Track when linked Purchase Invoice is fully paid.
   • Fields: costs_fully_paid, date_costs_fully_paid.

3.6 Module Settings

Add to Transport Settings, Sea Freight Settings, Air Freight Settings, Logistics Settings (as applicable):

Setting	Type	Default	Description
create_purchase_invoice_from_costs	Check	0	Allow creating PI from job/shipment costs
require_purchasing_process	Check	0	If enabled, use PR → PO → PI instead of direct PI
default_cost_supplier	Link → Supplier	—	Default supplier when charge has no pay_to
auto_create_purchase_invoice_on_complete	Check	0	Auto-create PI when job/shipment status = Completed

---

4. Data Model Summary

4.1 Job/Shipment Level

Transport Job / Air Shipment / Sea Shipment / Warehouse Job / Declaration
├── sales_invoice (Link)
├── purchase_invoice (Link) — NEW
├── fully_invoiced (Check) — NEW
├── date_fully_invoiced (Date) — NEW
├── fully_paid (Check) — NEW
└── date_fully_paid (Date) — NEW

4.2 Charge Level (Cost Charges)

Transport Job Charges / Air Shipment Charges / Sea Freight Charges / etc.
├── pay_to (Link → Supplier) — Sea Freight has; add to others as needed
├── estimated_cost / buying_amount / unit_cost
└── purchase_invoice (Link) — NEW, optional per-row

4.3 Custom Fields on ERPNext Core

DocType	Field	Type	Purpose
Sales Invoice Item	reference_doctype	Link → DocType	Link to source job
Sales Invoice Item	reference_name	Dynamic Link	Job/shipment name
Purchase Invoice	reference_doctype	Link → DocType	Link to source job
Purchase Invoice	reference_name	Dynamic Link	Job/shipment name
Purchase Invoice Item	reference_doctype	Link → DocType	For Recognition Engine
Purchase Invoice Item	reference_name	Dynamic Link	Job/shipment name

---

5. Implementation Phases

Phase	Scope	Effort
Phase 1	Add standard monitoring fields (fully_invoiced, fully_paid, date_fully_invoiced, date_fully_paid) to job/shipment doctypes	Low
Phase 2	Add custom fields to Sales Invoice Item for reference_doctype / reference_name; populate when creating SI from job	Low
Phase 3	Implement create_purchase_invoice() for Transport Job, Air Shipment, Sea Shipment; add purchase_invoice link	Medium
Phase 4	Add custom fields to Purchase Invoice / Purchase Invoice Item; wire Recognition Engine	Low
Phase 5	Add module settings; implement require_purchasing_process (PR → PO → PI)	Medium
Phase 6	Hooks to update fully_invoiced, fully_paid, date_fully_invoiced, date_fully_paid from SI/Payment Entry	Medium

---

6. Reference: Existing Code Locations

Component	Path
Transport Job create_sales_invoice	logistics/transport/doctype/transport_job/transport_job.py
Air Shipment create_sales_invoice	logistics/air_freight/doctype/air_shipment/air_shipment.py
Sea Shipment create_sales_invoice	logistics/sea_freight/doctype/sea_shipment/sea_shipment.py
Warehouse Job create_sales_invoice	logistics/warehousing/api_parts/ops.py
Declaration create_sales_invoice	logistics/customs/doctype/declaration/declaration.py
Recognition Engine (revenue/cost)	logistics/job_management/recognition_engine.py
Billing Status Reports	logistics/air_freight/report/billing_status_report/, logistics/sea_freight/report/sea_freight_billing_status_report/

---

7. Related Documents

• ACCOUNTS_TAB_STANDARDIZATION_REPORT.md — Accounts fields on doctypes
• LOGISTICS_MODULE_INTEGRATION_DESIGN.md — Cross-module integration
• SPECIAL_PROJECTS_MODULE_DESIGN.md — Project costing and billing

---

Document generated from codebase analysis.