Fulfillment

Overview

A fulfillment represents the physical process of getting ordered items to a customer. Each fulfillment moves through a lifecycle of statuses, from creation to delivery. An order can have multiple fulfillments (e.g., split shipments from different warehouses).

Create Fulfillment

Create a fulfillment by specifying the order and the line items to fulfill. You can partially fulfill an order by including only a subset of items. The fulfillment starts in pending status.

const whale = new WhaleClient("wk_live_...");

const fulfillment = await whale.fulfillments.create({
  order_id: "550e8400-e29b-41d4-a716-446655440000",
  type: "shipment",
  items: [
    {
      order_item_id: "item_001",
      quantity: 2
    },
    {
      order_item_id: "item_003",
      quantity: 1
    }
  ],
  notes: "Fragile — double box the ceramic mug"
});

// Response
{
  "object": "fulfillment",
  "id": "ful_7a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "type": "shipment",
  "items": [
    { "order_item_id": "item_001", "quantity": 2 },
    { "order_item_id": "item_003", "quantity": 1 }
  ],
  "tracking": null,
  "created_at": "2026-03-10T09:00:00.000Z"
}

Update Status

Transition a fulfillment through the pick-pack-ship lifecycle. Status transitions are validated — you cannot skip steps or move backward. Each transition timestamps the event for audit trails.

// Move from pending → allocated
await whale.fulfillments.update("ful_7a2b3c4d...", {
  status: "allocated",
  location_id: "loc_warehouse_east"
});

// Move from allocated → picked
await whale.fulfillments.update("ful_7a2b3c4d...", {
  status: "picked",
  picked_by: "staff_jane"
});

// Move from picked → packed
await whale.fulfillments.update("ful_7a2b3c4d...", {
  status: "packed",
  package_count: 1,
  total_weight: 2.4,
  weight_unit: "lb"
});

// Move from packed → shipped (requires tracking info)
await whale.fulfillments.update("ful_7a2b3c4d...", {
  status: "shipped",
  carrier: "usps",
  tracking_number: "9400111899223456789012",
  tracking_url: "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012"
});

Add Tracking

Attach carrier tracking information to a fulfillment. When tracking is added, customers receive an automatic notification with the tracking link. Supported carriers include USPS, UPS, FedEx, DHL, and any custom carrier.

await whale.fulfillments.update("ful_7a2b3c4d...", {
  carrier: "fedex",
  tracking_number: "794644790138",
  tracking_url: "https://www.fedex.com/fedextrack/?trknbr=794644790138",
  estimated_delivery: "2026-03-14T17:00:00.000Z"
});

// Response
{
  "object": "fulfillment",
  "id": "ful_7a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "status": "shipped",
  "tracking": {
    "carrier": "fedex",
    "tracking_number": "794644790138",
    "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=794644790138",
    "estimated_delivery": "2026-03-14T17:00:00.000Z"
  },
  "shipped_at": "2026-03-10T14:30:00.000Z",
  "notification_sent": true
}

List Fulfillments

Retrieve fulfillments with optional filters. Use status to find items at a specific stage, or order_id to see all fulfillments for a given order.

// List all fulfillments awaiting packing
const pending = await whale.fulfillments.list({
  status: "picked",
  limit: 50
});

// List fulfillments for a specific order
const orderFulfillments = await whale.fulfillments.list({
  order_id: "550e8400-e29b-41d4-a716-446655440000"
});

// Filter by date range
const thisWeek = await whale.fulfillments.list({
  created_after: "2026-03-03T00:00:00Z",
  created_before: "2026-03-10T23:59:59Z",
  status: "delivered"
});

API Reference