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.
purchase-orders:writeGrant 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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.