Evaluate a what-if cash forecast scenario

POST /api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan

Run the canonical forecast twice (clean baseline + scenario) and return the per-week ending-cash delta.

Read-only: overrides and inline_one_time_items apply only to the scenario pass and are never persisted. Persisting a scenario is a separate call to PUT /cash-forecast/overrides.

Operation ID: cfo_portal_evaluate_demand_plan_api_v1_businesses__business_id__cfo_portal_cash_forecast_demand_plan_post · View as markdown · OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Parameters

Path

business_id string required

Request body

Schema: DemandPlanScenarioRequest

scenario_description string required

overrides array · DemandPlanScenarioOverride DemandPlanScenarioOverride

3 fields

week_number integer required
column string required: One of: ar_in, ap_out, inventory, debt, budget_rev, budget_exp, one_time
amount_cents integer required

inline_one_time_items array · DemandPlanScenarioOneTime DemandPlanScenarioOneTime

3 fields

label string required
amount_cents integer required
applies_on string · date required

weeks integer

budget_id string

excluded_budget_ledger_ids array · string

Responses

201 Successful Response

Schema: DemandPlanScenarioResponse

scenario_description string required

weeks array · CashForecastWeek requiredCashForecastWeek

19 fields

week integer required: 1-indexed week within the horizon
start_date string · date required: Inclusive start date
end_date string · date required: Inclusive end date
cash_in_cents integer: Projected inflows from open invoices due in this week
ap_out_cents integer: Projected outflows from open bills due in this week
po_out_cents integer: Projected outflows from POs with expected delivery in this week
debt_out_cents integer: Projected outflows from scheduled debt payments in this week
budget_revenue_cents integer: Weekly budgeted revenue projection (prorated from monthly budget lines)
budget_expense_cents integer: Weekly budgeted expense projection (prorated from monthly budget lines)
budget_breakdown BudgetCalculationWeekBreakdown BudgetCalculationWeekBreakdown: Detailed ledger-by-ledger breakdown of budgeted amounts
one_time_cents integer: Net one-time payment delta for this week from user-defined one-time items (positive = inflow, negative = outflow).
ending_cash_cents integer: Projected ending cash balance after this week. = prior ending + cash_in + budget_rev + one_time - (ap + po + debt + budget_exp)
ar_in_overridden boolean
ap_out_overridden boolean
po_out_overridden boolean
debt_out_overridden boolean
budget_revenue_overridden boolean
budget_expense_overridden boolean
one_time_overridden boolean

week_deltas array · DemandPlanWeekDelta requiredDemandPlanWeekDelta

5 fields

week integer required
start_date string · date required
baseline_ending_cash_cents integer required
scenario_ending_cash_cents integer required
delta_cents integer required

starting_cash_cents integer required

baseline_ending_cash_cents integer required

scenario_ending_cash_cents integer required

ending_cash_delta_cents integer required

baseline_lowest_cash_cents integer required

scenario_lowest_cash_cents integer required

lowest_cash_delta_cents integer required

baseline_lowest_cash_week integer

scenario_lowest_cash_week integer

headline string required

narrative string required

warnings array · string

400 Bad Request - Invalid input

401 Unauthorized - Authentication required

403 Forbidden - Insufficient permissions

404 Not Found - Resource does not exist

422 Validation Error

Schema: HTTPValidationError

detail array · ValidationError ValidationError

5 fields

loc array · string | integer required
msg string required
type string required
input object
ctx object

Code samples

POST /api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan

bash

curl -X POST 'https://api.ondayzero.com/api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_description": "string"
}'

javascript

const response = await fetch('https://api.ondayzero.com/api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "scenario_description": "string"
}),
});
const data = await response.json();

python

import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {
  "scenario_description": "string"
}

response = httpx.post("https://api.ondayzero.com/api/v1/businesses/{business_id}/cfo-portal/cash-forecast/demand-plan", headers=headers, json=payload)
data = response.json()