> ## 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.

# Campaign counts and booked value by status

> Powers the KPI card row on the **Campaigns** screen.

A campaign is included in the period if its date range overlaps with the requested period (`start_date <= period_end AND end_date >= period_start`). Contract value is resolved from the latest `LeadContract` on the parent lead.

| Field | Definition |
|---|---|
| `active` | `node != NODE_SALES_END` AND not in a global action status |
| `on_hold` | `status = 'Pause'` (global workflow pause action) |
| `cancelled` | `status = 'Cancelled'` (global workflow reject action) |
| `completed` | `node = 'NODE_SALES_END'` (terminal workflow node) |
| `active_booked_value` | Sum of contract values for active campaigns |
| `completed_value` | Sum of contract values for completed campaigns |

> **Note:** `collected_value` is not available here — payment data lives in the payment service. Use `active_booked_value` as the booked figure.



## OpenAPI

````yaml /openapi/commercial.yaml get /api/v1/analytics/campaigns/summary
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/campaigns/summary:
    get:
      tags:
        - Campaigns
      summary: Campaign counts and booked value by status
      description: >-
        Powers the KPI card row on the **Campaigns** screen.


        A campaign is included in the period if its date range overlaps with the
        requested period (`start_date <= period_end AND end_date >=
        period_start`). Contract value is resolved from the latest
        `LeadContract` on the parent lead.


        | Field | Definition |

        |---|---|

        | `active` | `node != NODE_SALES_END` AND not in a global action status
        |

        | `on_hold` | `status = 'Pause'` (global workflow pause action) |

        | `cancelled` | `status = 'Cancelled'` (global workflow reject action) |

        | `completed` | `node = 'NODE_SALES_END'` (terminal workflow node) |

        | `active_booked_value` | Sum of contract values for active campaigns |

        | `completed_value` | Sum of contract values for completed campaigns |


        > **Note:** `collected_value` is not available here — payment data lives
        in the payment service. Use `active_booked_value` as the booked figure.
      operationId: analytics_campaigns_summary_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/CampaignSummary'
              examples:
                May2026:
                  value:
                    total: 75
                    active: 47
                    on_hold: 6
                    cancelled: 4
                    completed: 18
                    active_booked_value: '28200000.00'
                    completed_value: '9800000.00'
                    active_pct: '62.7'
                  summary: May 2026
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    CampaignSummary:
      type: object
      properties:
        total:
          type: integer
        active:
          type: integer
        on_hold:
          type: integer
        cancelled:
          type: integer
        completed:
          type: integer
        active_booked_value:
          type: string
          format: decimal
          pattern: ^-?\d{0,16}(?:\.\d{0,2})?$
        completed_value:
          type: string
          format: decimal
          pattern: ^-?\d{0,16}(?:\.\d{0,2})?$
        active_pct:
          type: string
          format: decimal
          pattern: ^-?\d{0,4}(?:\.\d{0,1})?$
      required:
        - active
        - active_booked_value
        - active_pct
        - cancelled
        - completed
        - completed_value
        - on_hold
        - total
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````