Skip to main content

Rank Forecast Builds

POST 

/api/cash-buying/rank

Rank forecast builds that already finished across all their suppliers against the buying capacity, and return the cash plan (the weekly strip, the ranked lines and the totals) — the same shape as cash_plan on Build Forecast.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Each per-supplier build returns a cash_build_id: Build Forecast (Single Supplier) returns it on a synchronous result (null without the cash_buying.index permission), and a queued build carries it on the completed job result from Get Job Status (it equals the job_id). Send one id per supplier build. Build inputs are kept for 24 hours; payment terms and supplier minimum thresholds are read from the suppliers when you rank. If the same supplier appears twice, the last id wins.

Read-only: nothing is created or ordered, and the plan is not saved (run_id is null). To pin lines, persist the forecast run and use Get Forecast Run Cash Plan / Pin Forecast Run Line.

Body:

  • build_ids (required, array of 1–500 distinct UUIDs): the cash_build_id of each finished supplier build.
  • pricing_tier_ids (optional, object): supplier id → supplier pricing tier id (or null for the product's first tier). Use it when a supplier's pricing tier was changed after the build: that supplier's lines are re-priced on the tier before ranking, so the plan's cash matches what the purchase orders will cost. Suppliers not listed keep the cost their build priced them at. 422 when a tier does not exist.

Balance keys follow Get Weekly Headroom: omitted without cash_buying.view_balances.

Errors: 422 when a build id has expired (rebuild the forecast) or when no buying capacity is set up; 422 validation errors for missing or malformed ids.

Permission: cash_buying.index. Token scope: purchase-orders:write.

Costs and payment terms: a line priced in a foreign currency is ranked at its cost converted to your home currency (the currency's conversion rate, the same rate a new purchase order takes); a line whose currency has no rate is excluded. A supplier's fixed-amount payment milestones are paid once per supplier order, out of its first fitted line (flag fixed_milestone), and percentage milestones apply to the rest. When the build enforced case packs, partial fits stay whole-pack multiples.

sized_unit_cost (on each line): the unit cost, in the line's pricing currency (as the purchase order carries it), that the line's cash was sized at. Compare it with the product's current cost to tell a plan ranked at old costs from the current ones; null on plans saved before it was recorded.

Request​

Responses​

OK

Response Headers
    Content-Type