{"openapi":"3.1.0","info":{"title":"POST /api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan","version":"1.0.0","description":"Evaluate a what-if cash forecast scenario"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan":{"post":{"tags":["cfo-portal"],"summary":"Evaluate a what-if cash forecast scenario","description":"Run the canonical forecast twice (clean baseline + scenario) and\nreturn the per-week ending-cash delta.\n\nRead-only: ``overrides`` and ``inline_one_time_items`` apply only\nto the scenario pass and are never persisted. Persisting a\nscenario is a separate call to ``PUT /cash-forecast/overrides``.","operationId":"cfo_portal_evaluate_demand_plan_api_v1_businesses__business_id__cfo_portal_cash_forecast_demand_plan_post","parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","title":"Business Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandPlanScenarioRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandPlanScenarioResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"detail":"Resource not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BudgetCalculationItem":{"properties":{"ledger_id":{"type":"string","title":"Ledger Id"},"ledger_name":{"type":"string","title":"Ledger Name"},"amount_cents":{"type":"integer","title":"Amount Cents"}},"type":"object","required":["ledger_id","ledger_name","amount_cents"],"title":"BudgetCalculationItem","description":"A single ledger's contribution to a week's budgeted total."},"BudgetCalculationWeekBreakdown":{"properties":{"revenue_items":{"items":{"$ref":"#/components/schemas/BudgetCalculationItem"},"type":"array","title":"Revenue Items"},"expense_items":{"items":{"$ref":"#/components/schemas/BudgetCalculationItem"},"type":"array","title":"Expense Items"}},"type":"object","title":"BudgetCalculationWeekBreakdown","description":"Breakdown of budget calculations for a single week."},"CashForecastWeek":{"properties":{"week":{"type":"integer","title":"Week","description":"1-indexed week within the horizon"},"start_date":{"type":"string","format":"date","title":"Start Date","description":"Inclusive start date"},"end_date":{"type":"string","format":"date","title":"End Date","description":"Inclusive end date"},"cash_in_cents":{"type":"integer","title":"Cash In Cents","description":"Projected inflows from open invoices due in this week","default":0},"ap_out_cents":{"type":"integer","title":"Ap Out Cents","description":"Projected outflows from open bills due in this week","default":0},"po_out_cents":{"type":"integer","title":"Po Out Cents","description":"Projected outflows from POs with expected delivery in this week","default":0},"debt_out_cents":{"type":"integer","title":"Debt Out Cents","description":"Projected outflows from scheduled debt payments in this week","default":0},"budget_revenue_cents":{"type":"integer","title":"Budget Revenue Cents","description":"Weekly budgeted revenue projection (prorated from monthly budget lines)","default":0},"budget_expense_cents":{"type":"integer","title":"Budget Expense Cents","description":"Weekly budgeted expense projection (prorated from monthly budget lines)","default":0},"budget_breakdown":{"$ref":"#/components/schemas/BudgetCalculationWeekBreakdown","description":"Detailed ledger-by-ledger breakdown of budgeted amounts"},"one_time_cents":{"type":"integer","title":"One Time Cents","description":"Net one-time payment delta for this week from user-defined one-time items (positive = inflow, negative = outflow).","default":0},"ending_cash_cents":{"type":"integer","title":"Ending Cash Cents","description":"Projected ending cash balance after this week. = prior ending + cash_in + budget_rev + one_time - (ap + po + debt + budget_exp)","default":0},"ar_in_overridden":{"type":"boolean","title":"Ar In Overridden","default":false},"ap_out_overridden":{"type":"boolean","title":"Ap Out Overridden","default":false},"po_out_overridden":{"type":"boolean","title":"Po Out Overridden","default":false},"debt_out_overridden":{"type":"boolean","title":"Debt Out Overridden","default":false},"budget_revenue_overridden":{"type":"boolean","title":"Budget Revenue Overridden","default":false},"budget_expense_overridden":{"type":"boolean","title":"Budget Expense Overridden","default":false},"one_time_overridden":{"type":"boolean","title":"One Time Overridden","default":false}},"type":"object","required":["week","start_date","end_date"],"title":"CashForecastWeek","description":"One week in a cash forecast horizon."},"DemandPlanScenarioOneTime":{"properties":{"label":{"type":"string","maxLength":200,"minLength":1,"title":"Label"},"amount_cents":{"type":"integer","title":"Amount Cents"},"applies_on":{"type":"string","format":"date","title":"Applies On"}},"type":"object","required":["label","amount_cents","applies_on"],"title":"DemandPlanScenarioOneTime","description":"One inline one-time item to model in a scenario only."},"DemandPlanScenarioOverride":{"properties":{"week_number":{"type":"integer","maximum":104.0,"minimum":0.0,"title":"Week Number"},"column":{"type":"string","enum":["ar_in","ap_out","inventory","debt","budget_rev","budget_exp","one_time"],"title":"Column"},"amount_cents":{"type":"integer","title":"Amount Cents"}},"type":"object","required":["week_number","column","amount_cents"],"title":"DemandPlanScenarioOverride","description":"One cell override for an HTTP scenario evaluation request.\n\n``week_number=0`` targets the Overdue row; ``1..weeks`` targets a\nweekly cell. ``amount_cents`` is the literal value to use."},"DemandPlanScenarioRequest":{"properties":{"scenario_description":{"type":"string","maxLength":400,"minLength":1,"title":"Scenario Description"},"overrides":{"items":{"$ref":"#/components/schemas/DemandPlanScenarioOverride"},"type":"array","title":"Overrides"},"inline_one_time_items":{"items":{"$ref":"#/components/schemas/DemandPlanScenarioOneTime"},"type":"array","title":"Inline One Time Items"},"weeks":{"type":"integer","maximum":52.0,"minimum":1.0,"title":"Weeks","default":13},"budget_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Budget Id"},"excluded_budget_ledger_ids":{"items":{"type":"string"},"type":"array","title":"Excluded Budget Ledger Ids"}},"type":"object","required":["scenario_description"],"title":"DemandPlanScenarioRequest","description":"Inputs to ``POST /cfo-portal/cash-forecast/demand-plan``."},"DemandPlanScenarioResponse":{"properties":{"scenario_description":{"type":"string","title":"Scenario Description"},"weeks":{"items":{"$ref":"#/components/schemas/CashForecastWeek"},"type":"array","title":"Weeks"},"week_deltas":{"items":{"$ref":"#/components/schemas/DemandPlanWeekDelta"},"type":"array","title":"Week Deltas"},"starting_cash_cents":{"type":"integer","title":"Starting Cash Cents"},"baseline_ending_cash_cents":{"type":"integer","title":"Baseline Ending Cash Cents"},"scenario_ending_cash_cents":{"type":"integer","title":"Scenario Ending Cash Cents"},"ending_cash_delta_cents":{"type":"integer","title":"Ending Cash Delta Cents"},"baseline_lowest_cash_cents":{"type":"integer","title":"Baseline Lowest Cash Cents"},"scenario_lowest_cash_cents":{"type":"integer","title":"Scenario Lowest Cash Cents"},"lowest_cash_delta_cents":{"type":"integer","title":"Lowest Cash Delta Cents"},"baseline_lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Baseline Lowest Cash Week"},"scenario_lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scenario Lowest Cash Week"},"headline":{"type":"string","title":"Headline"},"narrative":{"type":"string","title":"Narrative"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["scenario_description","weeks","week_deltas","starting_cash_cents","baseline_ending_cash_cents","scenario_ending_cash_cents","ending_cash_delta_cents","baseline_lowest_cash_cents","scenario_lowest_cash_cents","lowest_cash_delta_cents","headline","narrative"],"title":"DemandPlanScenarioResponse","description":"Structured demand-plan scenario output (cents-based).\n\nMirrors the AI tool's output shape but returns integer cents\ninstead of formatted currency strings so the frontend can render\nconsistently with the rest of the cash-forecast UI."},"DemandPlanWeekDelta":{"properties":{"week":{"type":"integer","title":"Week"},"start_date":{"type":"string","format":"date","title":"Start Date"},"baseline_ending_cash_cents":{"type":"integer","title":"Baseline Ending Cash Cents"},"scenario_ending_cash_cents":{"type":"integer","title":"Scenario Ending Cash Cents"},"delta_cents":{"type":"integer","title":"Delta Cents"}},"type":"object","required":["week","start_date","baseline_ending_cash_cents","scenario_ending_cash_cents","delta_cents"],"title":"DemandPlanWeekDelta","description":"One week of baseline-vs-scenario comparison."},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}