Logistics

XBuddy Logistics gives you end-to-end visibility over your outbound and inbound shipments — from the moment a package is picked up to final delivery confirmation. Track every delivery event, manage routes, and resolve exceptions without switching between carrier portals.

Whether you run your own fleet or work with third-party carriers, Logistics centralizes shipment data so your customer service team can answer delivery queries instantly, and your operations team can identify bottlenecks across routes and carriers.

Key Features

Shipment creation with multi-package support and weight/dimension tracking
Real-time delivery event logging (scan events, GPS waypoints, status transitions)
Route management and batch assignment to drivers or carriers
Exception management with categorized exception types and resolution workflow
Exception badge indicators on shipment lists for immediate visibility
Customer-facing tracking page (shareable link per shipment)
Integration with Sales (auto-create shipment from confirmed order) and Inventory (deduct stock on dispatch)

📸

[Screenshot: Logistics — Shipment List with Exception Badges]

Placeholder — will be replaced with actual screenshot

▶

[Video: Logistics — Managing Shipments & Resolving Exceptions]

Watch on YouTube → @XBuddy (placeholder)

Getting Started

Connect your carrier accounts under Settings → Integrations
Create your first shipment manually or let Sales generate one from a confirmed order
Add delivery events as the package moves through the network
Test the exception flow by raising a delayed exception and then resolving it
Share the customer tracking link to see the public-facing tracking experience

Shipment Lifecycle

A shipment progresses through the following statuses:

Status	Description
`draft`	Created but not yet handed to carrier / driver
`pending_pickup`	Awaiting carrier pickup; tracking number assigned
`in_transit`	Package confirmed picked up and moving through network
`out_for_delivery`	With the last-mile driver for today’s delivery attempt
`delivered`	Confirmed delivered to recipient
`exception`	An issue has been raised — requires action before delivery can proceed
`cancelled`	Shipment voided; no further events expected

Note: A shipment in exception status can return to in_transit or out_for_delivery once the exception is resolved. The full status history is preserved in the delivery events log.

Exception Management

Exceptions capture unexpected events during a shipment’s journey. Raising an exception flags the shipment for attention without discarding its delivery history.

Raising an Exception

POST /logistics/shipments/:id/exception

Request body:

{
  "exceptionType": "failed_delivery_attempt",
  "reason": "Recipient not home. Left notice card.",
  "actionRequired": "Schedule redelivery or arrange customer collection."
}

Exception Types

Type	When to use
`delayed`	Shipment behind schedule due to carrier delay, weather, or volume surge
`address_issue`	Address incomplete, undeliverable, or disputed
`customs_hold`	Package held at border for documentation or duty payment
`damaged_in_transit`	Package damage reported by carrier or recipient
`failed_delivery_attempt`	Delivery attempted but recipient was unavailable

The shipment status automatically transitions to exception when this endpoint is called.

Resolving an Exception

POST /logistics/shipments/:id/resolve-exception

Request body:

{
  "resolution": "Redelivery scheduled for 2026-03-25. Customer confirmed availability."
}

After resolution the shipment status reverts to the appropriate active status (in_transit or out_for_delivery) based on the last non-exception event.

Exception Badge on Shipment List

Any shipment with an unresolved exception displays an amber Exception badge in the shipment list and on the shipment detail header. The badge is removed automatically when the exception is resolved. Dispatchers can filter the shipment list to exception status to see all outstanding issues at once.

React Hooks

XBuddy provides pre-built React Query hooks for exception management:

import { useRaiseShipmentException, useResolveShipmentException } from '@/hooks/useLogistics';
 
// Raise an exception
const { mutate: raiseException, isPending } = useRaiseShipmentException(shipmentId);
raiseException({ exceptionType: 'delayed', reason: '...', actionRequired: '...' });
 
// Resolve an exception
const { mutate: resolveException } = useResolveShipmentException(shipmentId);
resolveException({ resolution: 'Redelivery confirmed.' });

Both hooks invalidate the shipment detail query on success, so the UI updates immediately without a manual refresh.

Common Use Cases

E-commerce last-mile: An online retailer monitors all out-for-delivery shipments each morning and flags any exceptions raised overnight, resolving address issues before the driver’s route begins.
Import customs clearance: An importer logs a customs_hold exception on inbound shipments pending documentation, tracks the days held, and resolves the exception once the release is confirmed.
Damaged goods claim: A distributor records a damaged_in_transit exception with carrier scan evidence, providing a timestamped audit trail for the insurance or supplier claim process.

Quality Procurement