Supply Chain

Overview

The supply chain API covers every step of procurement. Create and manage suppliers, issue purchase orders, receive inventory against those orders, and track supplier invoices through payment. All records link back to inventory so stock levels update automatically on receipt.

Suppliers

Create a supplier record with contact information and lead time. Suppliers are referenced by purchase orders and invoices, giving you a single source of truth for each vendor relationship.

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

// Create a supplier
const supplier = await whale.suppliers.create({
  name: "Pacific Textiles Co.",
  email: "orders@pacifictextiles.com",
  phone: "+1-555-0142",
  lead_time_days: 14,
  payment_terms: "net_30",
  address: {
    street: "800 Harbor Blvd",
    city: "Long Beach",
    state: "CA",
    zip: "90802",
    country: "US"
  },
  notes: "Primary fabric supplier — minimum order $500"
});

// Response
{
  "object": "supplier",
  "id": "sup_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Pacific Textiles Co.",
  "email": "orders@pacifictextiles.com",
  "phone": "+1-555-0142",
  "lead_time_days": 14,
  "payment_terms": "net_30",
  "status": "active",
  "created_at": "2026-03-10T08:00:00.000Z"
}

Purchase Orders

Issue purchase orders to suppliers with line items specifying products, quantities, and unit costs. POs move through a lifecycle: draft, sent, partially_received, and received.

// Create a purchase order
const po = await whale.purchaseOrders.create({
  supplier_id: "sup_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  expected_delivery: "2026-03-24",
  items: [
    {
      product_id: "prod_001",
      variant_id: "var_001_blue_m",
      quantity: 200,
      unit_cost: 12.50
    },
    {
      product_id: "prod_002",
      variant_id: "var_002_black_l",
      quantity: 100,
      unit_cost: 18.00
    }
  ],
  shipping_cost: 350.00,
  notes: "Spring restock — deliver to warehouse east"
});

// Response
{
  "object": "purchase_order",
  "id": "po_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "supplier_id": "sup_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "draft",
  "expected_delivery": "2026-03-24",
  "items": [
    { "product_id": "prod_001", "variant_id": "var_001_blue_m", "quantity": 200, "unit_cost": 12.50 },
    { "product_id": "prod_002", "variant_id": "var_002_black_l", "quantity": 100, "unit_cost": 18.00 }
  ],
  "subtotal": 4300.00,
  "shipping_cost": 350.00,
  "total": 4650.00,
  "created_at": "2026-03-10T09:00:00.000Z"
}

Receive Inventory

Record received goods against a purchase order. Partial receipts are supported — receive what arrives and the PO moves to partially_received until all items are accounted for. Inventory stock levels update automatically on receipt.

// Receive inventory against a purchase order
await whale.purchaseOrders.receive("po_b2c3d4e5-f6a7-8901-bcde-f23456789012", {
  location_id: "loc_warehouse_east",
  items: [
    {
      product_id: "prod_001",
      variant_id: "var_001_blue_m",
      quantity_received: 200
    },
    {
      product_id: "prod_002",
      variant_id: "var_002_black_l",
      quantity_received: 75,
      notes: "25 units on backorder — expected next week"
    }
  ],
  received_at: "2026-03-24T14:30:00.000Z"
});

// Response
{
  "object": "purchase_order_receipt",
  "id": "rcpt_c3d4e5f6-a7b8-9012-cdef-345678901234",
  "purchase_order_id": "po_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "partially_received",
  "items": [
    { "product_id": "prod_001", "quantity_ordered": 200, "quantity_received": 200, "remaining": 0 },
    { "product_id": "prod_002", "quantity_ordered": 100, "quantity_received": 75, "remaining": 25 }
  ],
  "received_at": "2026-03-24T14:30:00.000Z"
}

Invoices

Track supplier invoices with line items and due dates. Link invoices to purchase orders for three-way matching (PO, receipt, invoice). Record payments to move invoices from pending to paid.

// Create a supplier invoice
const invoice = await whale.invoices.create({
  supplier_id: "sup_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  purchase_order_id: "po_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  invoice_number: "INV-PT-2026-0087",
  due_date: "2026-04-09",
  line_items: [
    {
      description: "Blue cotton fabric — 200 yards",
      quantity: 200,
      unit_price: 12.50,
      amount: 2500.00
    },
    {
      description: "Black denim fabric — 75 yards",
      quantity: 75,
      unit_price: 18.00,
      amount: 1350.00
    },
    {
      description: "Freight & handling",
      quantity: 1,
      unit_price: 350.00,
      amount: 350.00
    }
  ]
});

// Response
{
  "object": "supplier_invoice",
  "id": "sinv_d4e5f6a7-b8c9-0123-defg-456789012345",
  "supplier_id": "sup_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "purchase_order_id": "po_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "invoice_number": "INV-PT-2026-0087",
  "status": "pending",
  "due_date": "2026-04-09",
  "subtotal": 4200.00,
  "total": 4200.00,
  "amount_paid": 0,
  "balance_due": 4200.00,
  "created_at": "2026-03-10T10:00:00.000Z"
}

API Reference