How do I query cash flows?

Choosing a calculation version

Every cash flow API accepts an optional cashFlowCalculationVersion field (or query parameter on the GET APIs) controlling how LUSID resolves and filters cash flows before returning them:

If you don't supply the field, version 1 applies, unless FINBOURNE has enabled the version 2 default for your domain (see Migrating below). An explicit value in the request always wins over the domain default.

The version applies to: QueryBucketedCashFlows, QueryCashFlows, QueryBucketCashFlowDrillDown, GetBucketedCashFlows, GetPortfolioCashFlows, GetUpsertablePortfolioCashFlows and GetPortfolioCashLadder.

Note: The GetPortfolioCashStatement API is unaffected; it returns the same results under both versions.

What version 2 changes

Version 2 bundles three related behaviour changes. They were specified together and interact, so they are selected by one version value rather than individual switches:

1. Waterfall source resolution. Rather than reading cash flows from a single source, version 2 always resolves them through a priority waterfall: structured result store (SRS) > transaction > instrument. Instrument cash flows are the baseline; a transaction generated from an instrument event replaces its matching instrument cash flow (so a booked coupon is no longer double-counted alongside its forecast); manual transaction cash flows with no instrument counterpart are included; and where your recipe says an instrument's cash flows come from the SRS, the SRS document replaces both wholesale.          

   Note: The waterfall governs resolution, not what every endpoint returns. The instrument-cashflow views — QueryCashFlows, GetPortfolioCashFlows, GetUpsertablePortfolioCashFlows, and bucketed queries using the default InstrumentCashFlow representation — return the de-duplicated projection stream: a flow whose transaction won the waterfall is removed from the projection rather than re-listed as a transaction row. The complete resolved stream, including transaction-sourced flows, is returned by QueryBucketCashFlowDrillDown and by the PortfolioCashFlow and TransactionCashFlow representations. When reconciling a drill-down against a bucket produced with the InstrumentCashFlow representation, exclude drill-down rows whose sourceType is Transaction first.

2. Trade-date classification. When a transaction's trade date and settlement date straddle the query's effective date, the cash flow is classified (factual vs forecast) by trade date. Version 1 classifies by settlement date, so flows can shift bucket between the versions for unsettled trades.

3. Corporate action date filtering. Cash flows triggered by corporate action or credit events (for example an index CDS default payout) are only included when the event's effective date is on or before the query's effective date. Version 1 includes such flows even for events that have not yet occurred.

Additionally, every bucketed response calculated under version 2 embeds the bucket interval metadata columns — Valuation/Bucket/Start, Valuation/Bucket/End, Valuation/Bucket/StartInclusive, Valuation/Bucket/EndInclusive — describing exactly which payment dates each row aggregates. Feed these values unchanged into QueryBucketCashFlowDrillDown to retrieve the individual cash flows behind a bucket; the drilled-down flows reconcile exactly with the row's totals.

Features that require version 2

• Cash flow haircuts (haircutRules, for matching-adjustment and Solvency II liquidity analyses): supplying rules with version 1 returns an error rather than silently un-haircut numbers.

• Bucket drill-down (QueryBucketCashFlowDrillDown): always calculates under version 2, regardless of any requested version, so its per-flow numbers reconcile with the version 2 buckets it drills into.

Version 1 deprecation

Version 1 exists so that established integrations keep returning identical numbers while you migrate; it is deprecated and will be removed after a deprecation period. Any successful response calculated under version 1 — whether you requested it explicitly or received it by default — carries two response headers:

Deprecation: @1786147200
Link: <https://support.lusid.com/docs/how-do-i-query-cash-flows#cashflowcalculationversion>; rel="deprecation"; title="cashFlowCalculationVersion=1 is deprecated; set cashFlowCalculationVersion=2, its successor"

The Deprecation header is an RFC 9745 date marking when version 1 was deprecated (8 August 2026). If you see these headers in your responses, you are on the deprecated calculation path.

Migrating from version 1 to version 2

1. Run side by side. Issue the same request twice, with cashFlowCalculationVersion set to "1" and "2", and reconcile. Expect exactly these classes of difference:

   • cash flows that appeared twice (instrument forecast + booked transaction) now appear once, with the transaction winning;

   • flows from trades straddling the effective date may move bucket (trade-date classification);

   • payouts from corporate action or credit events dated after the effective date disappear;

   • bucketed responses gain the Valuation/Bucket/* metadata columns.

2. Pin version 2 explicitly in your requests once reconciled.

3. Or ask FINBOURNE to flip your domain's default to version 2, so requests that don't specify a version get version 2 — explicit "1" still works during the deprecation period. Contact your FINBOURNE representative or technical support.

A note on request strictness

The cash flow request bodies reject unrecognised fields with a 400 naming the offending member, rather than ignoring them. Because fields such as haircutRules and cashFlowCalculationVersion change the meaning of the numbers returned, a misspelled field — or a field from a newer SDK than your LUSID deployment understands — fails loudly instead of silently returning numbers with different semantics than you asked for. If you receive such a 400, check the spelling of the named field and that your LUSID deployment is recent enough to support it.