Skip to content

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:

FactorDescription
CostTotal carrier charges for the route
SLAEstimated transit time vs. required delivery date
CapacityReal-time carrier availability and volume caps
ReliabilityHistorical 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 EventDescription
picked_upPackage collected from origin
departed_originLeft origin country
in_transitIn international transit
arrived_destinationArrived in destination country
customs_processingUndergoing customs clearance
customs_clearedReleased by customs
out_for_deliveryWith last-mile carrier
deliveredDelivered to recipient
exceptionAn issue requiring attention

Exception Types ​

ExceptionTriggerAuto-Resolution
customs_holdCustoms flags shipmentProvide additional documentation
delivery_failedCarrier cannot deliverSchedule re-delivery or redirect
address_invalidAddress validation failsPrompt seller for correction
duty_disputeDuty amount contestedRecalculate with updated HS code

LogirAI — Cross-Border Logistics API for Retailers and Marketplaces