Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fatelessdev/translogiX/llms.txt

Use this file to discover all available pages before exploring further.

Every shipment in TranslogiX passes through a defined sequence of statuses from the moment it is created until it is either delivered or cancelled. This page explains each status, the rules that govern which transitions are permitted, who can trigger them, and the side effects that occur — such as a vehicle being marked as busy when it is assigned to a shipment.

​
Shipment statuses

TranslogiX defines six shipment statuses via the shipmentStatusEnum:
StatusMeaning
CREATEDShipment record exists but has not yet been assigned to a transporter or vehicle
ASSIGNEDA transporter and vehicle have been linked to the shipment
PICKED_UPThe vehicle has collected the cargo from the source location
IN_TRANSITThe shipment is actively moving toward the destination
DELIVEREDCargo has been successfully delivered; terminal state
CANCELLEDShipment was cancelled at any point before delivery; terminal state

​
Lifecycle flow

1

CREATED

A new shipment is created by an ADMIN or TRANSPORTER via POST /api/shipments. The record is saved with status CREATED.At this point the shipment has a unique packageCode, a source, a destination, a materialType, a grossWeightKg, a quantity, a pickupDate, and a deliveryDeadline. The transporterId, vehicleId, and routeId fields are optional and may be set immediately or later.If a vehicleId is provided at creation time, the vehicle’s status is automatically updated to BUSY.Valid next states: ASSIGNED, CANCELLED
2

ASSIGNED

An ADMIN or the owning TRANSPORTER sends a status update (PATCH /api/shipments/:id) with { "status": "ASSIGNED" }. The shipment must already have a vehicleId set; when the transition to ASSIGNED occurs the vehicle’s status is confirmed as BUSY.This state signals that logistics planning is complete and the vehicle is committed to this shipment.Valid next states: PICKED_UP, CANCELLED
3

PICKED_UP

The status is advanced to PICKED_UP once the driver collects the cargo from the source location. This transition is triggered via PATCH /api/shipments/:id with { "status": "PICKED_UP" } by an ADMIN or TRANSPORTER.Valid next states: IN_TRANSIT, CANCELLED
4

IN_TRANSIT

The shipment is on its way to the destination. The status advances to IN_TRANSIT via PATCH /api/shipments/:id with { "status": "IN_TRANSIT" }.Tracking updates can be appended throughout this stage to record intermediate locations, GPS coordinates, and timestamps.Valid next states: DELIVERED, CANCELLED
5

DELIVERED

When the cargo reaches its destination, the status is set to DELIVERED. This is a terminal state — no further transitions are possible.When a shipment is marked DELIVERED, the assigned vehicle’s status is automatically reset to AVAILABLE so it can be assigned to future shipments.Valid next states: (none)
CANCELLED can be reached from any non-terminal state (CREATED, ASSIGNED, PICKED_UP, IN_TRANSIT). Once a shipment is DELIVERED or CANCELLED, the status cannot be changed further.

​
Valid transition matrix

The allowed transitions are enforced server-side using VALID_STATUS_TRANSITIONS in lib/validations/index.ts. Any attempt to move to an unlisted state returns a 400 error. 
export const VALID_STATUS_TRANSITIONS: Record<string, string[]> = {
  CREATED:   ["ASSIGNED", "CANCELLED"],
  ASSIGNED:  ["PICKED_UP", "CANCELLED"],
  PICKED_UP: ["IN_TRANSIT", "CANCELLED"],
  IN_TRANSIT:["DELIVERED", "CANCELLED"],
  DELIVERED: [],
  CANCELLED: [],
};
Attempting to transition a shipment to an invalid next state returns: Cannot transition from {current} to {target}. Valid next states: {list}

​
Who can update shipment status

Status updates are restricted to ADMIN and TRANSPORTER roles. A TRANSPORTER can only update shipments that belong to their own transporter entity — attempts to modify another transporter’s shipment return 403 Forbidden.
RoleCan update any shipmentCan update own shipments
ADMINYesYes
TRANSPORTERNoYes
DRIVERNoNo
CUSTOMERNoNo

​
Key shipment fields

FieldTypeDescription
packageCodetextUnique identifier for the shipment; used for customer-facing tracking
sourcetextPickup address or location name
destinationtextDelivery address or location name
materialTypetextDescription of the cargo being transported
grossWeightKgdecimalTotal weight of cargo including packaging
tareWeightKgdecimalWeight of packaging alone (optional)
quantityintegerNumber of units in the shipment
pickupDatedateScheduled date for cargo collection
deliveryDeadlinedateLatest acceptable delivery date; must be on or after pickupDate
transporterIduuidLinked transporter; may be assigned at creation or later
vehicleIduuidAssigned vehicle; setting this marks the vehicle as BUSY
routeIduuidOptional link to a predefined route for distance and rate lookup

​
Vehicle status side effects

TranslogiX automatically manages vehicle availability as shipments move through their lifecycle:
A vehicle is set to BUSY in two situations:
  • When a shipment is created with a vehicleId already set.
  • When a shipment transitions to ASSIGNED and a vehicleId is present.
// From app/api/shipments/route.ts
if (validated.vehicleId) {
  await db.update(vehicles)
    .set({ status: "BUSY" })
    .where(eq(vehicles.id, validated.vehicleId));
}
Vehicles in MAINTENANCE status are not automatically affected by shipment lifecycle events. Their status must be managed separately through the vehicle management API.

​
Tracking updates

At any point during a shipment’s journey, location events can be appended as tracking updates. Each update records a location name, and optionally GPS coordinates (latitude and longitude). Tracking updates are append-only and are publicly accessible via the /track route using the shipment’s packageCode.

Build docs developers (and LLMs) love

Get started for freeTalk to us