Shipping
Overview
Shipments, tracking scans, non-delivery reports, freight audit, and claims. Carrier HTTP clients live under src/integrations, not in the courier master-data module.
Code map
| Piece | Path |
|---|---|
| Shipment | src/modules/operations/shipment |
| Tracking feature | src/modules/operations/shipment-tracking |
| Courier master | src/modules/operations/courier |
| NDR listener | ndr-shipment.listener.ts |
| Schema | 43-shipment.prisma |
Entities: Shipment, ShipmentItem, ShipmentTracking, ShipmentNdrEvent, ShipmentFreightAudit, ShipmentClaim, Courier.
Strategies found
integrationCode values with a strategy class: SHP, SHPINTL, DLH, BLD, BLDINTL, FDX, DTDC, SHWY, STP, PTR, ITL.
Seed codes with no strategy class found: NIP, PIK, SHYP, ARMX, AMZ. Whether they are placeholders is unknown.
Events and queues
shipment.status.changed is in-process. Consumers: fulfillment, NDR, return shipment.
| Job | Queue | Trigger |
|---|---|---|
poll-shipment-tracking | shipment_tracking_queue | Cron 0 */3 * * * |
refresh-shipment-tracking | same | ShipmentController |
Courier webhooks (Shiprocket, Shipway, iThink, and others that call WebhookQueue) enter webhook_queue.
ShipmentExceptionScheduler ticks every minute. Its body was not fully read.
Business rules
NDR writes NdrEventType rows inside a transaction, triggered from shipment.status.changed.
Unknown: whether a webhook and the 3-hour poller can apply the same scan twice. Deduping would depend on a tracking-event unique key. That key was not verified.
Failure scenarios
Carrier calls are partial-failure heavy. See Couriers and Labels.
API surface
Shipment and NDR controllers, plus per-carrier ship/cancel/track routes. OpenAPI for fields.