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)

Getting Started

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

Shipment Lifecycle

A shipment progresses through the following statuses:

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

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.

Workflows & Processes

Shipment Creation & Delivery Workflow

1. Auto-create from Sales — Confirmed sales order triggers shipment creation; items, address, and weight auto-populated
2. Label generation — System generates shipping label with carrier barcode; prints for warehouse
3. Pickup coordination — Carrier picks up shipment; tracking number assigned; customer receives tracking link
4. In-transit tracking — Shipment progresses through carrier network; status updates received via API/webhooks
5. Last-mile delivery — Carrier notifies of out-for-delivery; customer can confirm delivery instructions
6. Delivery confirmed — Driver scans final barcode or customer signs; status → “Delivered”; invoice marked as ready to settle

Exception Resolution Workflow

1. Exception detected — System or carrier reports issue (delayed, damaged, wrong address, etc.)
2. Shipment flagged — Status → “Exception”; red badge displays on shipment list; responsible team notified
3. Triage & action — Team investigates root cause; decides on resolution (redeliver, refund, replacement)
4. Resolution execution — Implement solution (e.g., schedule redeliver for next day)
5. Resolution documented — Record resolution details; attach evidence (photos, carrier notes, customer communication)
6. Shipment cleared — Status returns to “In Transit” or “Delivered” once resolved; exception removed

Integration Points

• Sales Module — Confirmed orders auto-trigger shipment creation; delivery status feeds back to Sales
• Inventory Module — Shipment deducts stock on dispatch; system tracks warehouse-to-customer movement
• Finance Module — Delivery confirmation triggers invoice settlement; payment processing after delivery
• CRM Module — Customer contact records pull delivery addresses; delivery status visible in customer timeline
• Analytics Module — On-time delivery %, exception rates, and carrier performance dashboards
• Carrier APIs — Real-time tracking events pulled from carriers (FedEx, UPS, local couriers)

FAQ

Q: Can I split a sales order across multiple shipments (partial shipments)?
A: Yes. From a sales order, create multiple shipments for different items or delivery dates. Each shipment tracked separately; order marked “complete” only when all shipments delivered.

Q: How long does tracking data stay visible after delivery?
A: Indefinitely. All shipment and delivery records retained in Logistics module for compliance, audit, and customer service reference.

Q: Can I change the delivery address after shipment is picked up?
A: Typically no (carrier doesn’t allow mid-route changes). Contact carrier directly for redirect requests; system records the request and updates status if approved.

Q: How do I handle international shipments with customs declarations?
A: Shipments flagged as “International” require customs forms (CN22/CN23). System prompts for HS codes and declared values; documents attached to shipment record.