> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capedigital.co.ke/llms.txt
> Use this file to discover all available pages before exploring further.

# Open sales pipeline funnel with per-stage value & conversion

> Powers the **Sales pipeline** block on the **Overview** screen and the funnel on the **Leads & pipeline** screen.

Covers the **open pipeline** — leads while `committed_at IS NULL`, ordered Captured → Deal Closing. Stages bucket on the workflow `node` code (stable; status labels are not). Per-stage `value` is the latest **approved** contract value (pending/rejected excluded).

Each `stages[]` entry carries:
| Field | Meaning |
|---|---|
| `count` | open leads currently at this stage |
| `signal` | plain-language read of what a cluster here means |

Scalar fields (`total_open`, `nurturing`, `proposals_sent`, `committed`, `pipeline_value`) accompany the funnel.

> **Note:** once a lead commits it becomes a Campaign — delivery, billing and collected cash are owned by the campaigns/payment analytics.



## OpenAPI

````yaml /openapi/commercial.yaml get /api/v1/analytics/sales/pipeline-funnel
openapi: 3.0.3
info:
  title: Commercial Service API
  version: 1.0.0
  description: |2-

        **Commercial Service API** - Lead management and campaign workflow system.

        ## Versioning
        The API uses URL path versioning (e.g., `/api/v1/`, `/api/v2/`).
        Current version: **v1**
        
servers:
  - url: https://api.capedigital.co.ke/commercial
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /api/v1/analytics/sales/pipeline-funnel:
    get:
      tags:
        - Pipeline
      summary: Open sales pipeline funnel with per-stage value & conversion
      description: >-
        Powers the **Sales pipeline** block on the **Overview** screen and the
        funnel on the **Leads & pipeline** screen.


        Covers the **open pipeline** — leads while `committed_at IS NULL`,
        ordered Captured → Deal Closing. Stages bucket on the workflow `node`
        code (stable; status labels are not). Per-stage `value` is the latest
        **approved** contract value (pending/rejected excluded).


        Each `stages[]` entry carries:

        | Field | Meaning |

        |---|---|

        | `count` | open leads currently at this stage |

        | `signal` | plain-language read of what a cluster here means |


        Scalar fields (`total_open`, `nurturing`, `proposals_sent`, `committed`,
        `pipeline_value`) accompany the funnel.


        > **Note:** once a lead commits it becomes a Campaign — delivery,
        billing and collected cash are owned by the campaigns/payment analytics.
      operationId: analytics_sales_pipeline_funnel_retrieve
      parameters:
        - in: query
          name: period
          schema:
            type: string
          description: |-
            Period string. Accepted formats:
            - `2026-05` — calendar month
            - `Q2-2026` — quarter (Q1–Q4)
            - `YTD-2026` — year to date
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineFunnel'
              examples:
                May2026:
                  value:
                    total_open: 38
                    nurturing: 26
                    proposals_sent: 16
                    committed: 11
                    pipeline_value: '18400000.00'
                    stages:
                      - key: nurturing
                        label: Nurturing
                        signal: Early sales effort.
                        count: 26
                      - key: qualification
                        label: Qualification
                        signal: Quality filter.
                        count: 5
                      - key: deal_closing
                        label: Deal Closing
                        signal: Controllable bottleneck.
                        count: 3
                  summary: May 2026
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    PipelineFunnel:
      type: object
      properties:
        total_open:
          type: integer
        nurturing:
          type: integer
        proposals_sent:
          type: integer
        committed:
          type: integer
        pipeline_value:
          type: string
          format: decimal
          pattern: ^-?\d{0,16}(?:\.\d{0,2})?$
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStage'
      required:
        - committed
        - nurturing
        - pipeline_value
        - proposals_sent
        - stages
        - total_open
    PipelineStage:
      type: object
      properties:
        key:
          type: string
        label:
          type: string
        signal:
          type: string
        count:
          type: integer
      required:
        - count
        - key
        - label
        - signal
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````