Core Concepts

Shipment State Machine

Every shipment in LogirAI follows a well-defined state machine. Transitions happen automatically as events are received from carriers, customs systems, and internal processes.

order_created → origin_consolidation → international_transit → customs_processing → courier_assigned → out_for_delivery → delivered

At any point, a shipment may enter an exception state. Exceptions are tracked separately and have their own resolution workflows.

Orders vs Shipments

• Order — a seller's request to ship goods from A to B. An order may produce one or more shipments.
• Shipment — a physical movement of goods along a specific route. Each shipment has its own tracking, documents, and carrier assignments.

Landed Cost

Landed cost is the total cost to get goods from origin to the buyer's door, including:

• Product cost
• Shipping / freight charges
• Import duties
• Taxes (VAT, GST, sales tax)
• Brokerage and handling fees

LogirAI computes landed cost upfront using HS code classification, trade agreements, and destination country rules.

Routing Engine

The routing engine evaluates available carrier options for each shipment leg and selects the best combination based on:

Factor	Description
Cost	Total carrier charges for the route
SLA	Estimated transit time vs. required delivery date
Capacity	Real-time carrier availability and volume caps
Reliability	Historical on-time delivery and exception rates

Normalized Tracking Events

Different carriers report tracking data in different formats. LogirAI normalizes all events into a unified schema:

LogirAI Event	Description
picked_up	Package collected from origin
departed_origin	Left origin country
in_transit	In international transit
arrived_destination	Arrived in destination country
customs_processing	Undergoing customs clearance
customs_cleared	Released by customs
out_for_delivery	With last-mile carrier
delivered	Delivered to recipient
exception	An issue requiring attention

Exception Types

Exception	Trigger	Auto-Resolution
customs_hold	Customs flags shipment	Provide additional documentation
delivery_failed	Carrier cannot deliver	Schedule re-delivery or redirect
address_invalid	Address validation fails	Prompt seller for correction
duty_dispute	Duty amount contested	Recalculate with updated HS code