---
title: "Understanding instrument lifecycle events emitted by LUSID"
slug: "understanding-instrument-lifecycle-events-emitted-by-lusid"
description: "Supported instrument events in LUSID"
updated: 2026-07-05T10:54:47Z
published: 2026-07-05T10:54:47Z
canonical: "support.lusid.com/understanding-instrument-lifecycle-events-emitted-by-lusid"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding instrument lifecycle events emitted by LUSID

LUSID can emit lifecycle events for [supported term instruments](/v1/docs/what-instruments-does-lusid-support), enabling you to handle those events in a seamless and consistent manner.

> [!WARNING]
> **Important**: To enable instrument events, register a recipe with every portfolio you wish events to impact. [More information](/v1/docs/setting-a-portfolio-recipe).

For example, LUSID automatically emits a `BondCouponEvent` each time a bond coupon is due. No user input is required, providing you have mastered the underlying instrument as either type `Bond`, `ComplexBond` or `InflationLinkedBond` in the LUSID Security Master. In addition:

- **LUSID provides** a `BondCouponEvent` [default transaction template](/v1/docs/what-is-a-transaction-template) that automatically generates a transaction representing each coupon amount on its ex-date. You can override this default template if you wish, but it is not necessary.
- **You must implement** a `BondCoupon` [transaction type](/v1/docs/what-is-a-transaction-type) to confer a suitable economic impact on automatically-generated bond coupon transactions. We provide a recommendation, which you can either implement as-is or change if desired.

> **Note**: Instruments of type `Equity` do not have a lifecycle in the normal sense but you can load a stream of corporate actions and trigger LUSID to emit appropriate events. [More information](/v1/docs/understanding-dedicated-corporate-action-events).

With the `BondCoupon` transaction type in place, for each portfolio with a holding in the bond instrument on the ex-date of each coupon, LUSID automatically:

1. Generates an [output transaction](/v1/docs/input-and-output-transactions) scaled to your holding in that portfolio, and enriched with extra information such as gain/loss or a tax calculation.
2. Implements the economic impact prescribed by the transaction type, for example adding the bond coupon amount to a particular cash balance.

> **Note**: If an event does not generate an output transaction, the issue usually relates to transaction type scopes and sources. [Troubleshooting guide](/v1/docs/how-does-lusid-resolve-transaction-templates-and-types-for-instrument-lifecycle-events).

## `Bond`, `ComplexBond` and `InflationLinkedBond` (but not MBS)

**Recommended reading**: [Handling bond coupon, principal and maturity events](/v1/docs/handling-bond-coupon-principal-and-maturity-instrument-lifecycle-events)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `BondCouponEvent` | ✅ Can also be manually loaded | ✅ | [BondCoupon](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#bondcouponevent) |
| `BondDefaultEvent` | ❌ [Must be manually loaded](/v1/docs/terminating-instrument-lifecycle-events-if-a-bond-issuer-defaults) | ❌ | N/A |
| `BondPrincipalEvent` | ✅ Can also be manually loaded | ✅ | [BondPrincipal](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#bondprincipalevent) |
| `ConsentEvent` (not ILB) | ❌ Must be manually loaded | ✅ | `ConsentAccept` |
| `ConversionEvent` | ❌ Must be manually loaded | ✅ | - [ConvRemoveExisting](/v1/docs/recommended-transaction-types-for-corporate-action-events#conversionevent) - [ConvAdjustCost](/v1/docs/recommended-transaction-types-for-corporate-action-events#convadjustcost-transaction-type) - [ConvReceiveCash](/v1/docs/recommended-transaction-types-for-corporate-action-events#convreceivecash-transaction-type) - [ConvReceiveUnits](/v1/docs/recommended-transaction-types-for-corporate-action-events#convreceiveunits-transaction-type) - [ConvCashInLieu](/v1/docs/recommended-transaction-types-for-corporate-action-events#convcashinlieu-transaction-type) |
| `DrawingEvent` (not ILB) | ❌ Must be manually loaded | ✅ | `BondDrawing` |
| `DutchAuctionEvent` (not ILB) | ❌ Must be manually loaded | ✅ | - `DutchAuctionRemoveExisting` - `DutchAuctionReceiveUnits` - `DutchAuctionCashSettlement` - `DutchAuctionCashInLieu` |
| `EarlyRedemptionEvent` | ❌ [Must be manually loaded](/v1/docs/terminating-instrument-lifecycle-events-if-a-bond-issuer-redeems-early) | ✅ | - [BondEarlyRedemption](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#earlyredemptionevent) - [BondEarlyRedemptionAccrued](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#bondearlyredemptionaccrued-transaction-type) |
| `ExchangeOfferEvent` (not ILB) | ❌ Must be manually loaded | ✅ | - `ExchangeRemoveExisting` - `ExchangeReceiveUnits` - `ExchangeCashInLieu` - `ExchangeReceiveCash` |
| `InterestPaymentEvent` | ❌ Must be manually loaded | ✅ | `InterestPayment` |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `PutRedemptionEvent` | ❌ Must be manually loaded | ✅ | - `BondEarlyRedemption` - `BondEarlyRedemptionAccrued` |
| `RepurchaseOfferEvent` | ❌ Must be manually loaded | ✅ | - `RepurchaseOfferEventChooseCash` - `RepurchaseOfferEventCashAccrued` - `RepurchaseOfferEventChooseTender` - `RepurchaseOfferEventTenderAccrued` |
| `SpinOffEvent` | ❌ Must be manually loaded | ✅ | - `SpinOffAdjustCost` - `SpinOffNewUnits` - `SpinOffCashInLieu` |
| `TenderEvent` | ❌ Must be manually loaded | ✅ | - `TenderRemoveExisting` - `TenderAdjustCost` - `TenderReceiveCash` - `TenderReceiveUnits` - `TenderCashInLieu` - `TenderEventCashAccrued` |
| `WorthlessEvent` (not ILB) | ❌ Must be manually loaded | ✅ | `Worthless` |

## MBS (modelled as a `ComplexBond`)

To convert, default or redeem an MBS early, contact [Technical Support](/v1/docs/how-do-i-use-the-support-centre).

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `MbsCouponEvent` | ✅ | ✅ | [MbsCoupon](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#mbscouponevent) |
| `MbsInterestDeferralEvent` | ✅ | ✅ | [MbsInterestDeferral](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#mbsinterestdeferralevent) |
| `MbsInterestShortfallEvent` | ✅ | ✅ | [MbsInterestShortfall](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#mbsinterestshortfallevent) |
| `MbsPrincipalEvent` | ✅ | ✅ | [MbsPrincipal](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#mbsprincipalevent) |
| `MbsPrincipalWriteOffEvent` | ✅ | ✅ | [MbsPrincipalWriteOff](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#mbsprincipalwriteoffevent) |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |

## `CdsIndex` and `CreditDefaultSwap`

**Recommended reading**: [Handling premium, credit and maturity events](/v1/docs/handling-premium-and-credit-events-for-cdx-instruments)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `CreditPremiumCashFlowEvent` | ✅ | ✅ | [CreditPremiumCashFlow](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#creditpremiumcashflowevent) |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `ProtectionPayoutCashFlowEvent` | ❌ [Triggered by loading CdxCreditEvent or CdsCreditEvent](/v1/docs/handling-premium-and-credit-events-for-cdx-instruments#handling-credit-events) | ✅ | [ProtectionPayoutCashFlow](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#protectionpayoutcashflowevent) |

## `EquityOption`, `ExchangeTradedOption` and `InterestRateSwaption`

**Recommended reading**: [Handling exercise or expiry events](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments)

Note for an ETO the underlying must be an `Equity` or `Future`. Other underlyings do not support instrument events

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `OptionExerciseCashEvent` (if cash-settled) | ❌ [Triggered by event instruction](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments#exercising-a-cashsettled-option) | ✅ | [CashSettledOptionExercise](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#optionexercisecashevent) |
| `OptionExercisePhysicalEvent` (if physically-settled) | ❌ [Triggered by event instruction](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments#exercising-a-physicallysettled-option) | ✅ | - [PhysicallySettledOptionExercise](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#optionexercisephysicalevent) - [CallOptionPhysicalExercise](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#calloptionphysicalexercise-transaction-type) (if call option) - [PutOptionPhysicalExercise](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#putoptionphysicalexercise-transaction-type) (if put option) |
| `MergerEvent` (`EquityOption` only) | ❌ Must be manually loaded | ✅ | - `MergerRemoveExisting` - `MergerAdjustCost` - `MergerReceiveCash` - `MergerReceiveUnits` - `MergerCashInLieu` |
| `ExpiryEvent` | ✅ Only if unexercised | ✅ Only if unexercised | [Expiry](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#expiryevent) |

## `FlexibleRepo`

**Recommended reading**: [Handling cashflow, collateral, payment and closure events](/v1/docs/handling-instrument-events-for-repurchase-agreements)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `FlexibleRepoCashFlowEvent` | ✅ | ✅ | [FlexibleRepoCashTransfer](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#flexiblerepocashflowevent) |
| `FlexibleRepoCollateralEvent` | ✅ | ✅ | [FlexibleRepoCollateralTransfer](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#flexiblerepocollateralevent) |
| `FlexibleRepoInterestPaymentEvent` | ✅ | ✅ | [FlexibleRepoInterestPayment](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#flexiblerepointerestpaymentevent) |
| `FlexibleRepoFullClosureEvent` | ❌ [Must be manually loaded](/v1/docs/handling-instrument-events-for-repurchase-agreements#fully-closing-an-open-repo) | ❌ | N/A |
| `FlexibleRepoPartialClosureEvent` | ❌ [Must be manually loaded](/v1/docs/handling-instrument-events-for-repurchase-agreements#partially-closing-a-repo) | ❌ | N/A |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |

## `Future`

**Recommended reading**: [Handling mark to market and expiry events](/v1/docs/handling-future-mark-to-market-and-expiry-events)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `FutureMarkToMarketEvent` | ✅ | ✅ | [FutureMarkToMarket](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#futuremarktomarketevent) |
| `FutureExpiryEvent` | ✅ | ✅ | [FutureCashSettlement](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#futureexpiryevent) |

## `FxForward`

**Recommended reading**: [Handling settlement and close out events for deliverable forwards](/v1/docs/handling-fxforward-settlement-and-maturity-instrument-lifecycle-events)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `FxForwardSettlementEvent` | ✅ | ✅ | - [FxForwardDomPrincipal and FxForwardFgnPrincipal](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#fxforwardsettlementevent) (if deliverable) - `NdfSettlement` (if NDF) |
| `EarlyCloseOutEvent` | ❌ [Must be manually loaded](/v1/docs/handling-fxforward-settlement-and-maturity-instrument-lifecycle-events#closing-a-position-early) | ✅ | `EarlyCloseOutSettlement` |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |

## `InterestRateSwap`

**Recommended reading**: [Handling cashflow and principal events](/v1/docs/handling-instrument-events-for-interest-rate-swaps)

| Lifecycle event | Automatically emitted by LUSID? | Event generates output transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- |
| `SwapCashFlowEvent` | ✅ | ✅ | [SwapCashFlow](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#swapcashflowevent) |
| `SwapPrincipalEvent` | ✅ | ✅ | [SwapPrincipal](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#swapprincipalevent) |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |

## Other instrument types

| **LUSID instrument type** | **Lifecycle event** | Automatically emitted by LUSID? | Event generates transactions? | **Transaction types requiring implementation** |
| --- | --- | --- | --- | --- |
| `CapFloor` | `CapletFloorletCashFlowEvent` | ✅ | ✅ | `CapletFloorletCashFlow` |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `ContractForDifference` | `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `EquitySwap` | `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `FlexibleDeposit` | `DepositInterestPaymentEvent` | ✅ | ✅ | - `DepositInterestPayment` - `DepositInterestPaymentBalanceAdjustment` |
| `UpdateDepositAmountEvent` | ❌ Must be manually loaded | ✅ | `UpdateDepositAmount` |
| `DepositRollEvent` | ❌ Must be manually loaded | ✅ | - `DecreaseBalance` - `IncreaseBalance` - `WithdrawInterest` - `ReinvestInterest` |
| `DepositCloseEvent` | ❌ Must be manually loaded | ✅ | - `DepositCloseInterestPayment` - `DepositCloseFinalBalanceRepayment` - `DepositClose` |
| `FlexibleLoan` | `LoanInterestRepaymentEvent` | ✅ Can also be manually loaded | ✅ | `LoanInterestRepayment` |
| `LoanPrincipalRepaymentEvent` | ✅ Can also be manually loaded | ✅ | - `LoanBalanceReduction` - `LoanLimitReduction` - `TermLoanFacilityLimitDecrease` - `RevolvingLoanFacility` |
| `ForwardRateAgreement` | `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `FxSwap` | `FxForwardSettlementEvent` | ✅ | ✅ | `FxForwardPrincipal` |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `InflationSwap` | `SwapCashFlowEvent` | ✅ | ✅ | [SwapCashFlow](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#swapcashflowevent) |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `LoanFacility` | `ContractInitialisationEvent` | ❌ Must be manually loaded | ✅ | `InitialiseContract` |
| `AdjustGlobalCommitmentEvent` | ❌ Must be manually loaded | ✅ | `AdjustGlobalCommitment` |
| `DrawdownEvent` | ❌ Must be manually loaded | ✅ | - `DrawdownFacilityBalance` - `IncreaseContractBalance` |
| `LoanInterestRepaymentEvent` | ✅ Can also be manually loaded | ✅ | `LoanInterestRepayment` |
| `LoanFacilityContractRolloverEvent` | ❌ Must be manually loaded | ❌ | N/A |
| `LoanPrincipalRepaymentEvent` | ✅ Can also be manually loaded | ✅ | - `LoanBalanceReduction` - `LoanLimitReduction` - `TermLoanFacilityLimitDecrease` - `RevolvingLoanFacility` |
| `LoanFacilityDelayedCompensationPaymentEvent` | ❌ Must be manually loaded | ✅ | `LoanFacilityDelayedCompensationPayment` |
| `TermDeposit` | `TermDepositInterestEvent` | ✅ | ✅ | `TermDepositInterest` |
| `TermDepositPrincipalEvent` | ✅ | ✅ | `TermDepositPrincipal` |
| `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |
| `TotalReturnSwap` | `MaturityEvent` | ✅ | ✅ | [Maturity](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent) |

##