Returns an Actual-vs-Plan variance comparison for every cash flow category over a date range.
For each category, surfaces the actual total, the planned total (what was forecast when
the period was still in the future), the variance (actual − planned), and the variance
as a percentage of the plan.
Use this when the user wants to know:
- "Which categories came in over or under budget last quarter?"
- "How did our payroll compare to plan in Q1?"
- "Where did actual inflows beat or miss our forecast?"
- "Give me a budget vs actual breakdown for last month."
- "What was the biggest variance category this year?"
Variance sign convention (consistent for both cashIn and cashOut):
- Positive variance → favorable: actuals exceeded plan for cashIn, or spending was
below plan for cashOut (cashOut values are negative, so actual less negative = positive).
- Negative variance → unfavorable: cashIn below plan, or cashOut above plan (overspent).
For meaningful results, use a historical (or mostly historical) date range — plan comparison
is only available where isHistorical=true periods exist. Future periods contribute actuals
but will have null planned values.
grouping controls the time granularity of per-period arrays. For month-over-month analysis
use MONTHLY; for week-by-week use WEEKLY. Match the granularity to the range length.
Output shape:
- periods[]: period headers with periodStart, periodEnd, isHistorical (true = past)
- cashIn / cashOut: each has aggregate actual, planned, variance, variancePct and
categories[] sorted by absolute variance (largest deviations first).
Each category has categoryName, categoryId, actual, planned, variance, variancePct,
plus per-period arrays: actualByPeriod, plannedByPeriod, varianceByPeriod.
varianceByPeriod entries are null for future periods (no plan comparison available).
- categoryId can be passed as groupId to getCashFlowBreakdown for drill-down detail
(e.g. to see which customers or vendors drove the variance in a specific category).