Sales Pipeline

Overview

The sales pipeline gives you a structured view of your deals from first contact to close. Define custom stages that match your sales process, create deals with values and probabilities, and track weighted pipeline value for revenue forecasting.

Configure Stages

Define the stages of your pipeline. Each stage has a display order and optional terminal flags — is_won and is_lost — that mark it as a closing state. Deals in terminal stages are excluded from active pipeline metrics.

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

// Create pipeline stages in order
const stages = [
  { name: "Lead",          display_order: 1 },
  { name: "Qualified",     display_order: 2 },
  { name: "Proposal Sent", display_order: 3 },
  { name: "Negotiation",   display_order: 4 },
  { name: "Closed Won",    display_order: 5, is_won: true },
  { name: "Closed Lost",   display_order: 6, is_lost: true }
];

for (const stage of stages) {
  await whale.pipelineStages.create(stage);
}

// Response (for "Closed Won")
{
  "object": "pipeline_stage",
  "id": "stg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Closed Won",
  "display_order": 5,
  "is_won": true,
  "is_lost": false,
  "deal_count": 0,
  "created_at": "2026-03-10T09:00:00.000Z"
}

Create & Move Deals

Create a deal with a monetary value, win probability, and contact information. Move deals between stages as they progress. The weighted_value is calculated automatically as value times probability.

// Create a new deal
const deal = await whale.deals.create({
  title: "Acme Corp Annual Contract",
  value: 48000,
  currency: "usd",
  probability: 0.6,
  stage_id: "stg_qualified...",
  contact_name: "John Rivera",
  contact_email: "john@acmecorp.com",
  expected_close_date: "2026-04-15",
  notes: "Interested in enterprise plan, needs SSO integration"
});

// Response
{
  "object": "deal",
  "id": "deal_f1e2d3c4-b5a6-7890-fedc-ba0987654321",
  "title": "Acme Corp Annual Contract",
  "value": 48000,
  "weighted_value": 28800,
  "probability": 0.6,
  "stage": { "id": "stg_qualified...", "name": "Qualified" },
  "contact_name": "John Rivera",
  "contact_email": "john@acmecorp.com",
  "expected_close_date": "2026-04-15",
  "created_at": "2026-03-10T11:00:00.000Z"
}

// Move deal to next stage
await whale.deals.update("deal_f1e2d3c4...", {
  stage_id: "stg_proposal_sent...",
  probability: 0.75
});

Pipeline Summary

Get an aggregated view of your pipeline showing deal count and weighted value per stage. Use this for revenue forecasting and identifying bottlenecks in your sales process.

const summary = await whale.pipeline.summary();

// Response
{
  "object": "pipeline_summary",
  "total_deals": 34,
  "total_value": 892000,
  "total_weighted_value": 423600,
  "stages": [
    { "name": "Lead",          "deal_count": 12, "total_value": 186000, "weighted_value": 37200 },
    { "name": "Qualified",     "deal_count": 8,  "total_value": 264000, "weighted_value": 105600 },
    { "name": "Proposal Sent", "deal_count": 6,  "total_value": 198000, "weighted_value": 118800 },
    { "name": "Negotiation",   "deal_count": 4,  "total_value": 152000, "weighted_value": 121600 },
    { "name": "Closed Won",    "deal_count": 3,  "total_value": 72000,  "weighted_value": 72000 },
    { "name": "Closed Lost",   "deal_count": 1,  "total_value": 20000,  "weighted_value": 0 }
  ],
  "period": "all_time"
}

API Reference