--- title: "The open buy on each supplier's terms clock" method: GET path: "/api/v1/commitments/cash-gate" tags: ["commitments"] --- # The open buy on each supplier's terms clock `GET /api/v1/commitments/cash-gate` ## Request - Base URL: `https://api.app.tightly.io` - URL: `https://api.app.tightly.io/api/v1/commitments/cash-gate` - Auth: HTTP bearer Fifty-two retail weeks of merchandise cash: what comes in from what sold and, on the weeks ahead, from the plan of record; what goes out as the open buy lands on each supplier's own billing lag; the balance walked against a declared floor; and the levers that would move the tightest weeks. IT IS MERCHANDISE CASH AND NOT A CASH-FLOW STATEMENT. Nothing here knows about payroll, rent, tax or financing. It answers one question: can the coming weeks pay for the buy we intend. TWO CASH-OUT LINES, AND ADDING THEM DOUBLE-COUNTS. `contracted_out` is the placed open buy moved onto the week each supplier actually bills, measured from that supplier's own bills and falling back to its declared terms. `planned_out` is what the plan of record still implies before a purchase order exists. They overlap by construction, because a placed order is already subtracted from the plan's need. Weeks are numbered on the organisation's own 4-5-4 grid (`fiscal_week`, FY26-W36) with the ISO week of the same Sunday beside it. A term that is not on file is null with its reason and never a guess; where the two declarations the ladder walks against are missing, `not_measured` names them. THE FORWARD LEG CAN BE SERVED UNREAD. On a big enough book, projecting the weeks ahead can run past the time this read gives it; that leg alone is then dropped, `projected_in_source` is null and `projected_in_reason` says why. Read that field rather than inferring it from a run of nulls. Scope: `cash:read`. ## Query parameters - `include_projection` boolean - `commitment_id` string - `weeks` integer - `scenario` string - `view` 'summary' ## Headers - `Tightly-Version` string ## Response `200` opening_balance_usd and cash_floor_usd (both DECLARED, null where nobody has said, and named in not_measured); as_of (the day the ladder stands on) and computed_at (the instant it was worked out); weeks as [{fiscal_week, iso_week, begins, settled_in, basis, committed_in, contracted_out, planned_out, planned_out_lag_source}] where fiscal_week is the org's 4-5-4 retail week (FY26-W36) and iso_week the ISO week of the same Sunday (2026-W35), and planned_out is null wherever the plan side was not read, no plan cell places money into the week, or the identity did not fire, and planned_out_lag_source is measured | declared | unmeasured (the weakest word of everything placed into that week); served_weeks as {served, computed, note}, on every answer whether or not weeks was sent, so the window is read off the payload rather than off the length of a list; groups as [{key, name, open_buy_usd, terms_days, terms_source, terms_measured_from, weekly_draw_usd}] largest exposure first, each weekly_draw_usd in weeks order and null where the terms are unknown (a row of zeros means terms that pay after the window); levers as [{key, name, why, reversible, releases, buy_effect_usd, reason}] with releases [{group_key, cash_usd}] or null; unlagged_open_buy_usd and undated_open_buy_usd (open buy with no terms, and with no delivery date: said, never absorbed); projected_through; unpriced_projected_units; committed_in_source; projected_in_source (forward_curve where the projection was read, null where it was not) and projected_in_reason (the sentence beside an unread projection, null where it was read, so the two are never both set); contracted_out_source (placed | freight | placed+freight | no_open_buy, and null where NEITHER leg behind contracted_out could speak for the year -- every dollar of the open buy behind a house with no terms on file and no container plan quoting freight; every week's contracted_out is then null too, because fifty-two zeros beside an open buy of millions say the book takes nothing out of the bank all year. no_open_buy is the opposite reading and a measured zero: the order pad is empty); unpriced_committed_units; planned_out_coverage (commitments / planned / folded / measured / cap / months_dropped / cells / cells_incomplete / calendar / commitments_read / categories / reason; a capped total is never presented as the whole plan. measured is what the cap bounds -- the money reads this read PERFORMED, which is folded plus the ones that ran and then failed -- so it is never smaller than folded); planned_out_before_window_usd and planned_out_after_window_usd (planned money the ladder cannot hold, said apart: what bills before its first week, a month underway on terms shorter than the days of it already gone, and what bills past the served year) ## Other responses - `401`: No usable key: malformed, unknown, revoked, expired or stopped. One refusal covers all five, telling a caller which is which maps the surface for them. A request with no Authorization header at all is refused 400 before any key is looked for. - `403`: The key may not reach this operation. `plan_excludes` when Cash is sold with Pro and this organisation's plan does not include it; `scope_missing` when the key does not hold Cash; `organization_mismatch` when the path names an organisation that is not the key's; `ip_not_allowed` when the caller's address is outside the key's allowlist. - `429`: The key has spent its allowance for this minute. 600 reads and 120 writes a minute, counted per key, refused calls included. `Retry-After` says how long to wait. - `503`: The database is briefly out of reach, which is what a failover or a full connection pool looks like from outside. Wait the seconds `Retry-After` names and send the request again. A read is safe to repeat. A write is not, because the connection was lost in the middle of it, so read the object back before sending it a second time. Branch on the status rather than on `code`, which is `POSTGRES_UNAVAILABLE` from one of the two seams that raise this and `SERVICE_UNAVAILABLE` from the other. --- [API](https://skmtc.dev/tightly/apis/tightly-api.md) · [All operations](https://skmtc.dev/tightly/apis/tightly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tightly/apis/tightly-api/revisions/199f7eb35afb?raw)