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

# Get Series

> Time-series invoiced vs collected — feeds line charts and grouped bar charts.

Each point in `series` has:
- `date` — x-axis label (ISO date or YYYY-MM for monthly)
- `invoiced` — KES recognised (accrual basis)
- `collected` — KES received (cash basis)
- `gap` — invoiced minus collected (positive = clients paying late)
- `invoice_count` / `payment_count` — event counts for tooltips

**Recommended chart:** grouped bar (`invoiced` vs `collected` per bucket)
or dual-line with area fill between lines to show the accrual-cash gap.
Zero-value buckets are included so the x-axis is always continuous.



## OpenAPI

````yaml /openapi/payment.yaml get /api/v1/payments/stats/series
openapi: 3.1.0
info:
  title: Cape Media - Payment Service
  description: >-
    Invoice requests, invoice uploads, payment tracking, and commission
    management.
  version: 1.0.0
servers:
  - url: https://api.capedigital.co.ke/payment
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /api/v1/payments/stats/series:
    get:
      tags:
        - Payments
      summary: Get Series
      description: >-
        Time-series invoiced vs collected — feeds line charts and grouped bar
        charts.


        Each point in `series` has:

        - `date` — x-axis label (ISO date or YYYY-MM for monthly)

        - `invoiced` — KES recognised (accrual basis)

        - `collected` — KES received (cash basis)

        - `gap` — invoiced minus collected (positive = clients paying late)

        - `invoice_count` / `payment_count` — event counts for tooltips


        **Recommended chart:** grouped bar (`invoiced` vs `collected` per
        bucket)

        or dual-line with area fill between lines to show the accrual-cash gap.

        Zero-value buckets are included so the x-axis is always continuous.
      operationId: get_series_api_v1_payments_stats_series_get
      parameters:
        - name: period
          in: query
          required: false
          schema:
            type: string
            description: >-
              Reporting window. One of the preset windows below, or **custom**
              (requires `date_from` and `date_to`):

              - **today** — current day only

              - **week** — Monday of the current week to today

              - **mtd** — Month To Date: 1st of this month to today

              - **qtd** — Quarter To Date: 1st of this quarter to today (e.g.
              Apr 1 in Q2)

              - **ytd** — Year To Date: Jan 1 to today

              - **rolling_30** — last 30 calendar days, regardless of month
              boundaries

              - **rolling_60** — last 60 calendar days

              - **rolling_90** — last 90 calendar days (standard treasury
              lookback)

              - **custom** — supply `date_from=YYYY-MM-DD&date_to=YYYY-MM-DD`
            default: mtd
            title: Period
          description: >-
            Reporting window. One of the preset windows below, or **custom**
            (requires `date_from` and `date_to`):

            - **today** — current day only

            - **week** — Monday of the current week to today

            - **mtd** — Month To Date: 1st of this month to today

            - **qtd** — Quarter To Date: 1st of this quarter to today (e.g. Apr
            1 in Q2)

            - **ytd** — Year To Date: Jan 1 to today

            - **rolling_30** — last 30 calendar days, regardless of month
            boundaries

            - **rolling_60** — last 60 calendar days

            - **rolling_90** — last 90 calendar days (standard treasury
            lookback)

            - **custom** — supply `date_from=YYYY-MM-DD&date_to=YYYY-MM-DD`
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            description: >-
              Time bucket size for the x-axis:

              - **daily** — one point per day (best for: today, week, mtd,
              rolling_30)

              - **weekly** — one point per Mon–Sun week (best for: rolling_60,
              rolling_90, qtd)

              - **monthly** — one point per month (best for: ytd, custom long
              ranges)
            default: daily
            title: Granularity
          description: >-
            Time bucket size for the x-axis:

            - **daily** — one point per day (best for: today, week, mtd,
            rolling_30)

            - **weekly** — one point per Mon–Sun week (best for: rolling_60,
            rolling_90, qtd)

            - **monthly** — one point per month (best for: ytd, custom long
            ranges)
        - name: date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: Start date for period='custom' (YYYY-MM-DD).
            title: Date From
          description: Start date for period='custom' (YYYY-MM-DD).
        - name: date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: End date for period='custom' (YYYY-MM-DD).
            title: Date To
          description: End date for period='custom' (YYYY-MM-DD).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````