Shipment Events

Shipment events are triggered when shipments are created, updated, change status, have items assigned, or are deleted.

TypeScript Interfaces

Copy these interfaces to type your webhook handlers:

/** Base event properties included in all webhook events */
interface BaseEvent {
  /** Unique event identifier (UUID) */
  id: string;
  /** Event type */
  kind: string;
  /** ISO 8601 timestamp */
  time: string;
  /** Transaction identifier for grouping related events */
  transactionId: string;
}

/** Shipment status values */
type ShipmentStatus =
  | "onHold"
  | "ready"
  | "pending"
  | "loaded"
  | "shipped"
  | "inTransit"
  | "completed"
  | "canceled";

---

shipment.created

Triggered when a new shipment is created.

Example

{
  "id": "evt_abc123",
  "kind": "shipment.created",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "orderId": "ord_789",
  "destination": "Toronto Warehouse"
}

TypeScript

interface ShipmentCreatedEvent extends BaseEvent {
  kind: "shipment.created";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Associated order UUID, if any */
  orderId?: string;
  /** Destination name, if set */
  destination?: string;
}

---

shipment.updated

Triggered when any tracked field on a shipment changes. The changes object contains only the fields that changed, each with from and to values.

Overlap with shipment.status.changed

When a shipment’s status changes, both shipment.updated and shipment.status.changed fire for the same change. Subscribe to shipment.status.changed if you only care about status transitions. Subscribe to shipment.updated if you want all field changes in one event.

Example

{
  "id": "evt_abc123",
  "kind": "shipment.updated",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "changes": {
    "status": { "from": "onHold", "to": "shipped" },
    "destination": { "from": null, "to": "Toronto Warehouse" }
  }
}

TypeScript

interface ShipmentChanges {
  status?: { from: ShipmentStatus | null; to: ShipmentStatus | null };
  destination?: { from: string | null; to: string | null };
  transportId?: { from: string | null; to: string | null };
  dueDate?: { from: string | null; to: string | null };
  notes?: { from: string | null; to: string | null };
  [field: string]: { from: unknown; to: unknown } | undefined;
}

interface ShipmentUpdatedEvent extends BaseEvent {
  kind: "shipment.updated";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Fields that changed, each with from/to values */
  changes: ShipmentChanges;
}

---

shipment.status.changed

Triggered when a shipment’s status is updated.

Note

shipment.status.changed is a focused convenience event. When a status change occurs, shipment.updated also fires with status included in its changes object.

Example

{
  "id": "evt_abc123",
  "kind": "shipment.status.changed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "previousShipmentStatus": "pending",
  "currentShipmentStatus": "in_transit"
}

TypeScript

interface ShipmentStatusChangedEvent extends BaseEvent {
  kind: "shipment.status.changed";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Status before this change */
  previousShipmentStatus: ShipmentStatus;
  /** New status after this change */
  currentShipmentStatus: ShipmentStatus;
}

Status Values

Status	Description
onHold	Shipment on hold, awaiting action
ready	Shipment ready to be loaded
pending	Shipment pending dispatch
loaded	Shipment loaded onto transport
shipped	Shipment dispatched
inTransit	Shipment in transit to destination
completed	Shipment delivered and completed
canceled	Shipment cancelled

---

shipment.items.assigned

Triggered when items are assigned to a shipment for a specific order.

Example

{
  "id": "evt_abc123",
  "kind": "shipment.items.assigned",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentOrderId": "ord_789"
}

TypeScript

interface ShipmentItemsAssignedEvent extends BaseEvent {
  kind: "shipment.items.assigned";
  /** Shipment UUID */
  shipmentId: string;
  /** Order UUID that items were assigned for */
  shipmentOrderId: string;
}

---

shipment.deleted

Triggered when a shipment is deleted.

Example

{
  "id": "evt_abc123",
  "kind": "shipment.deleted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456"
}

TypeScript

interface ShipmentDeletedEvent extends BaseEvent {
  kind: "shipment.deleted";
  /** Shipment UUID */
  shipmentId: string;
}

---

All Shipment Event Types

Union type for handling any shipment event:

type ShipmentEvent =
  | ShipmentCreatedEvent
  | ShipmentUpdatedEvent
  | ShipmentStatusChangedEvent
  | ShipmentItemsAssignedEvent
  | ShipmentDeletedEvent;

// Type guard for shipment events
function isShipmentEvent(event: BaseEvent): event is ShipmentEvent {
  return event.kind.startsWith("shipment.");
}

// Example webhook handler
async function handleShipmentWebhook(event: ShipmentEvent) {
  switch (event.kind) {
    case "shipment.created":
      console.log(`New shipment created: ${event.shipmentShortId}`);
      break;

    case "shipment.updated":
      console.log(`Shipment ${event.shipmentShortId} was updated`);
      break;

    case "shipment.status.changed":
      console.log(
        `Shipment ${event.shipmentShortId} changed from ${event.previousShipmentStatus} to ${event.currentShipmentStatus}`
      );

      if (event.currentShipmentStatus === "in_transit") {
        // Send tracking notification to customer
      } else if (event.currentShipmentStatus === "delivered") {
        // Update order fulfillment status
      }
      break;

    case "shipment.items.assigned":
      console.log(
        `Items assigned to shipment ${event.shipmentId} for order ${event.shipmentOrderId}`
      );
      break;

    case "shipment.deleted":
      console.log(`Shipment ${event.shipmentId} was deleted`);
      break;
  }
}