Shipping

Configure shipping methods, create shipments, and track deliveries through every stage of the fulfillment process.

ShippingMethod Model

class ShippingMethod {
  id: string;              // Unique UUID identifier
  name: string;            // Method name (e.g. "Standard", "Express")
  carrier: string;         // Carrier name (e.g. "DHL", "FedEx")
  baseCost: number;        // Base cost in cents (e.g. 999 = $9.99)
  estimatedDays: number;   // Estimated delivery days
  isActive: boolean;       // Active status (default: true)
}

Shipment Model

class Shipment {
  id: string;                  // Unique UUID identifier
  orderId: string;             // Associated order ID
  shippingMethodId: string;    // Shipping method used
  trackingNumber: string | null; // Carrier tracking number
  status: ShipmentStatus;      // Current shipment status
  shippedAt: Date | null;      // When the shipment was shipped
  deliveredAt: Date | null;    // When the shipment was delivered
  shippingAddress: string;     // Delivery address
}

enum ShipmentStatus {
  PENDING      // Shipment created, not yet picked up
  PICKED_UP    // Carrier has picked up the package
  IN_TRANSIT   // Package is in transit
  DELIVERED    // Package has been delivered
  RETURNED     // Package was returned
  CANCELLED    // Shipment was cancelled
}

Shipment Status Workflow

100%

Loading diagram...

Shipping Operations

Shipping Methods

Create a shipping method:

import { createServices } from "commercio";

const { shippingService } = createServices();

// Create a shipping method
const method = await shippingService.createShippingMethod({
  name: "Standard Shipping",
  carrier: "DHL",
  baseCost: 999,         // $9.99 in cents
  estimatedDays: 5,
});

console.log(method.id);            // UUID
console.log(method.name);          // "Standard Shipping"
console.log(method.carrier);       // "DHL"
console.log(method.baseCost);      // 999
console.log(method.estimatedDays); // 5
console.log(method.isActive);      // true

List shipping methods:

// Get all active shipping methods
const methods = await shippingService.getActiveShippingMethods();

methods.forEach(method => {
  console.log(`${method.carrier} - ${method.name}: $${method.baseCost / 100}`);
});

Update a shipping method:

// Update shipping method details
const updated = await shippingService.updateShippingMethod(method.id, {
  baseCost: 1299,        // Increase to $12.99
  estimatedDays: 3,
});

console.log(updated.baseCost);      // 1299
console.log(updated.estimatedDays); // 3

Deactivate a shipping method:

// Deactivate a shipping method
const deactivated = await shippingService.deactivateShippingMethod(method.id);

console.log(deactivated.isActive); // false

// Deactivated methods won't appear in getActiveShippingMethods()

Complete Example

import { createServices } from "commercio";

const { shippingService } = createServices();

// 1. Create a shipping method
const dhl = await shippingService.createShippingMethod({
  name: "Express Shipping",
  carrier: "DHL",
  baseCost: 1499,         // $14.99
  estimatedDays: 2,
});

// 2. Create a shipment for an order
const shipment = await shippingService.createShipment({
  orderId: order.id,
  shippingMethodId: dhl.id,
  shippingAddress: "456 Oak Ave, Los Angeles, CA 90001, US",
});

// 3. Add tracking number
await shippingService.addTrackingNumber(shipment.id, "DHL-9876543210");

// 4. Full delivery workflow
await shippingService.pickUpShipment(shipment.id);
console.log("Status: PICKED_UP");

await shippingService.transitShipment(shipment.id);
console.log("Status: IN_TRANSIT");

await shippingService.deliverShipment(shipment.id);
console.log("Status: DELIVERED");

// 5. Verify final state
const delivered = await shippingService.getShipmentById(shipment.id);
console.log(delivered.status);          // "DELIVERED"
console.log(delivered.trackingNumber);  // "DHL-9876543210"
console.log(delivered.deliveredAt);     // Date

Best Practices

1. Always Add Tracking Numbers

Assign tracking numbers as soon as the carrier provides them for visibility:

// Add tracking immediately after carrier confirms pickup
const shipment = await shippingService.createShipment({ ... });
await shippingService.addTrackingNumber(shipment.id, carrierTrackingId);

2. Use Costs in Cents

Store all monetary values in cents to avoid floating-point issues:

// Good: Use cents
const method = await shippingService.createShippingMethod({
  name: "Standard",
  carrier: "USPS",
  baseCost: 599, // $5.99
  estimatedDays: 7,
});

// Display to user
console.log(`Shipping: $${method.baseCost / 100}`); // "Shipping: $5.99"

3. Follow the Status Workflow

Always transition shipments through each status in order. Skipping statuses will throw errors:

// Good: Follow the workflow
await shippingService.pickUpShipment(shipment.id);
await shippingService.transitShipment(shipment.id);
await shippingService.deliverShipment(shipment.id);

// Bad: Skipping statuses
await shippingService.deliverShipment(shipment.id); // Error if still PENDING

4. Deactivate Instead of Delete

Deactivate shipping methods rather than deleting them to preserve historical shipment records:

// Deactivate instead of deleting
await shippingService.deactivateShippingMethod(method.id);

// Active methods for customer-facing selection
const methods = await shippingService.getActiveShippingMethods();