FTF Lifecycle

A subscription is the request to invest in an FTF. A holding is the live investment record created once an accepted subscription has been processed.

After calling /subscribe, use /subscription to track the returned subscription.uid until holdingUid is available. Once holdingUid exists, use /holding/{entity_code}/{holdingUid} or /holding and treat the holding as the source of truth.

The diagrams below show the typical lifecycle for Fixed and Extendable holdings. Boxes represent object statuses, and arrows represent lifecycle processes that move a holding from one status to another. Where a lifecycle process emits a public /event, the event type is shown in green on the arrow. Dashed connectors provide context, such as a rolled holding continuing through the same lifecycle, and do not represent public events.

How to read the statuses

Pending means the holding has been created from an accepted subscription, but has not yet been issued. Cash has not yet moved at this point — the wire from the entity arrives during the issuance step, not at subscription.

Issued means the holding is live. While a holding is issued, its economics or structure may still change through lifecycle processes such as adjustment or split.

CutOff means the holding has reached its cut-off point. The maturity action is locked and can no longer be changed through the API. From this point, TreasurySpring processing determines the next lifecycle step, such as redemption, roll, extension, or finalization depending on the product type and maturity action. CutOff is a holding status, not currently a public event.

PendingWithdrawal means a redemption has been requested but the cash payout to the entity's bank account has not yet been confirmed.

Redeemed means the holding has completed its lifecycle and has been redeemed.

Cancelled means a previously-issued holding was unwound before its natural maturity — for example because funding never arrived, or operational reversal. Emits a CANCELLED event.

Maturity actions

A holding's maturity action is the instruction for what happens to its value when it matures. Every holding exposes its current action(s) as maturityActions (see the Holding model); a holding may have more than one when its value is split across actions. The maturity action is what determines which lifecycle process runs at cut-off:

• HOLD — mature to cash, held within the cell.
• REDEEM — mature and withdraw the proceeds to the entity's bank account.
• ROLL — reinvest into a new holding of the same FTF.
• SWITCH — reinvest into a different FTF.

While a holding is Issued, the action can be changed via PUT/holding/{entity_code}/{holding_uid}/maturity-action. Once the holding reaches CutOff the action is locked and TreasurySpring processing applies it. After maturity, maturityActions continues to reflect the action(s) that were applied.

Default maturity action is ROLL

If a subscription request omits maturityAction, the holding defaults to ROLL rather than REDEEM. A holding left untouched at cut-off will be reinvested in the next FTF of the same product instead of being paid out to the entity's bank account.

This is an important detail worth setting explicitly. If your workflow expects cash on maturity, please send maturityAction: "Redeem" at subscribe time, or update it via the maturity-action endpoint while the holding is Issued.

Dates and times

The API uses three distinct representations for temporal values. Knowing which is which avoids off-by-an-hour bugs around daylight saving.

Kind	Example	Notes
Date	"2024-01-01"	A calendar date with no time and no timezone. Fields such as issueDate, maturityDate, subscriptionDate(s), and valueDate.
Datetime	"2024-01-01T12:15:00+00:00"	An instant in ISO 8601, always timezone-aware (carries a UTC offset). Fields such as Subscription.cutoffDatetime, Holding.cutoffDatetime, Indication.created, Indication.expiry, and Task.expiry. Parse these directly.
Time	"12:15:00"	A naive time-of-day in London local time (Europe/London), with no date and therefore no UTC offset. The only field of this kind is Indication.cutoffTime (see Cut-off timing).

Every datetime the API returns is timezone-aware, so you can compare and convert it without extra context. The single exception is Indication.cutoffTime, covered below.

Cut-off timing

For a vast majority of products, daily cut-off is 12:15 London time. Some products operate on their own schedule — UK T-bills, for example, have a different cut-off — so when scheduling work against the deadline, please read the authoritative value from the object you're working with rather than hardcoding a time:

Object	Field	Type	What it gives you
Indication	cutoffTime	time (naive)	Wall-clock time-of-day in London local time (Europe/London), the same for every subscriptionDate. Combine it with the subscriptionDate you intend to use to compute the cut-off datetime.
Subscription	cutoffDatetime	datetime (timezone-aware)	Cut-off datetime for the chosen subscriptionDate, already calendar-adjusted. Available as soon as the subscription is created.
Holding	cutoffDatetime	datetime (timezone-aware)	Cut-off datetime for the current period of the holding, calendar-adjusted. The authoritative value for any scheduling against the live position.

Indication.cutoffTime is the lightest-weight handle — useful before any subscription exists, e.g. to warn a user that they're about to submit a subscription close to cut-off. Once a subscription is placed, Subscription.cutoffDatetime is the precise value. Once a holding is issued, Holding.cutoffDatetime is the source of truth for the live position.

cutoffTime carries no UTC offset

cutoffTime is a naive time-of-day: it has no date and therefore no UTC offset. Because London observes daylight saving, the same 12:15 wall-clock time is 12:15Z under GMT (winter) but 11:15Z under BST (summer). Do not treat cutoffTime as UTC or as your own local time. To get an unambiguous instant, localise combine(subscriptionDate, cutoffTime) in the Europe/London zone — or simply read Subscription.cutoffDatetime / Holding.cutoffDatetime, which are already timezone-aware.

Cut-off schedules may evolve

Cut-off times can change over time. Reading the field from the object directly insulates your integration from those changes.

Subscription, funding, and late wires

Cash moves into the TreasurySpring cell at issuance, not at subscription. Submitting /subscribe creates a subscription record (and, after acceptance, a Pending holding) but does not reduce the entity's cash on hold in TreasurySpring.

If cash arrives before the cut-off of the requested subscription date, the holding issues on that date and the ISSUED event fires. If cash arrives after that cut-off, the holding does not error: TreasurySpring automatically re-targets it to the next available subscription date for the same FTF. The visible effect is that subscriptionDate, issueDate, and maturityDate shift forward by a day (or to the next business day for that product).

For reconciliation, treat the subscriptionDate on the holding as the source of truth once issuance happens — the subscription you originally submitted may show an earlier date.

Rolls produce two non-overlapping holdings

A ROLL action at cut-off creates a new holding rather than extending the existing one. The two holdings are non-overlapping in time:

• The original holding's maturityDate becomes the new holding's issueDate (or the next available subscription date).
• Both records remain queryable — the old holding moves to Redeemed, the new one starts at Pending then Issued.

When aggregating positions for reporting, use issue/maturity dates as the period boundaries to avoid double-counting. The SUBSCRIBED event for the successor holding fires immediately after the predecessor's redemption process completes.

Partial and early redemption (maturity value adjustment)

If part of a holding's value is redeemed before maturity, TreasurySpring uses a maturity value adjustment (MVA) rather than a separate fee charge. The process is:

1. The original holding is Split into two — the portion staying invested keeps its terms; the portion being withdrawn is segregated.
2. The withdrawing portion is Adjusted — its maturityValue is reduced to reflect early-exit pricing.
3. The adjusted portion is then Redeemed to the entity's bank account.

This produces three events for one logical "partial redemption": SPLIT, ADJUSTED, then REDEEMED. There is no separate fee field — the MVA is folded into the holding's maturityValue.

Fixed holding lifecycle

Fixed holdings have a simpler lifecycle: they are created, issued, reach cut-off, and are then either redeemed or rolled into a new holding.

Extendable holding lifecycle

Extendable holdings follow the same initial lifecycle, but may move from cut-off back to issued when extended. This can happen multiple times before the holding enters its final period and is eventually redeemed or rolled. The final-period boxes represent the same holding after Finalize; a new holding is only created when a holding is rolled.

Each extension of an extendable holding is recorded with its own yield, price per share, and new maturity date. To retrieve that history (most recent first), call GET/holding/{entity_code}/{holding_uid}/extension. Fixed holdings have no extensions.

The table below summarises the lifecycle processes shown in the diagrams. These process names are descriptive labels used in this guide; they may not exactly match internal TreasurySpring task names. Some transitions are initiated by API activity, while others are TreasurySpring scheduled or operational processes based on the current holding state and selected maturity action. The public event column shows the /event type emitted when that process produces an event. If no event is listed for a status change, query /holding to observe the latest state.

Lifecycle process	Applies to	Main effect	What drives it	Public event
Subscribe	Fixed, Extendable	Creates a holding from an accepted subscription	Client request followed by accepted subscription processing	SUBSCRIBED
Issue	Fixed, Extendable	Moves holding Pending to Issued; cash moves into the cell at this point	TreasurySpring issue processing	ISSUED
Adjust	Fixed, Extendable	Updates holding economics or key dates (including MVA for early/partial redemption)	TreasurySpring operational change while the holding is issued	ADJUSTED
Split	Fixed, Extendable	Splits one holding into separate holdings	TreasurySpring operational change while the holding is issued	SPLIT
Cut off	Fixed, Extendable	Moves holding Issued to CutOff	Scheduled TreasurySpring process once the holding reaches cutoffDatetime
Redeem	Fixed, Extendable	Moves holding CutOff to Redeemed	TreasurySpring maturity processing based on the selected maturity action	REDEEMED
Roll	Fixed; Extendable final period only	Creates the next (non-overlapping) holding from a cut-off holding	TreasurySpring maturity processing based on the selected maturity action	SUBSCRIBED, then ISSUED
Extend	Extendable only	Continues the holding with a new maturity date	TreasurySpring extendable maturity processing before the final period	EXTENDED
Finalize	Extendable only	Moves the same holding from CutOff to Issued in its final period	TreasurySpring extendable maturity processing into the final period	FINALIZED
Cancel	Fixed, Extendable	Unwinds a previously-issued holding (e.g. funding never arrived)	TreasurySpring operational process	CANCELLED

For reconciliation, use public events to detect lifecycle changes and use /holding/{entity_code}/{holdingUid} to retrieve the current authoritative holding state.