Terminating instrument events if a bond issuer redeems early

If a bond issuer redeems early, you can instruct LUSID to return the principal and interest accrued to date, and terminate instrument lifecycle events for an instrument of type Bond, ComplexBond or InflationLinkedBond.

To do this, manually load an EarlyRedemptionEvent into a corporate action source and subscribe each portfolio with a holding in that bond to the source. Note the following:

The EarlyRedemptionEvent specifies the redeem date and strike price.
LUSID terminates instrument lifecycle events of types BondCouponEvent, BondPrincipalEvent and MaturityEvent from this date. This means no subsequent transactions representing coupon and principal payments are generated. You should handle EarlyRedemptionEvent to set your holding(s) in the bond down to zero.
For a ComplexBond with an optionality schedule there is a more sophisticated flow. More information coming soon.

Step 1: Create a corporate action source

If a suitable corporate action source does not exist, call the CreateCorporateActionSource API, or use the Data Management > Corporate Actions dashboard in the LUSID web app, to create one. Note if the bond is stored in a custom instrument scope you should populate the instrumentScopes object, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
    "scope": "My-CAS-scope",
    "code": "My-CAS-code",
    "displayName": "Example corporate action source",
    "description": "This is an example corporate action source",
    "instrumentScopes": ["My-bond-instrument-scope"]
  }'

Call the UpsertPortfolioDetails API, or use the Data Management > Portfolios dashboard, to retrospectively subscribe each existing portfolio with a holding in the bond to the corporate action source, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/growth/uk-equities/details'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '{
  "corporateActionSourceId": {
    "scope": "My-CAS-scope",
    "code": "My-CAS-code"
  }
}'

Step 3: Implement transaction types for `EarlyRedemptionEvent`

EarlyRedemptionEvent automatically generates two output transactions in each portfolio with a holding in the bond:

The first transaction returns the principal at the strike price. It mandates a BondEarlyRedemption transaction type; you can specify any economic impact you like, but this recommendation reduces bond holding units down to zero and updates a cash holding by the principal amount (effectively selling the bond).
The second transaction returns interest accrued since the last bond coupon (if greater than zero). It mandates a BondEarlyRedemptionAccrued transaction type; you can give this any economic impact you like, but this recommendation updates a cash holding by the accrued amount.

Step 4: Load an `EarlyRedemptionEvent` into the corporate action source

Call the UpsertInstrumentEvents API, or use the Data Management > Corporate Actions dashboard, to load an EarlyRedemptionEvent into the corporate action source, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources/My-CAS-scope/My-CAS-code/instrumentevents'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '[
  {
    "instrumentEventId": "EarlyRedemption-2025-06-26",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003E33"},
    "description": "Redeem bond early and stop subsequent lifecycle events",
    "participationType": "Voluntary",
    "instrumentEvent": {
      "instrumentEventType": "EarlyRedemptionEvent",
      "effectiveDate": "2025-06-26T00:00:00.0000000+00:00",
      "currency": "GBP",
      "pricePerUnit": 1.01,
      "earlyRedemptionElections": [
        {
          "electionKey": "Redeem",
          "isChosen": true,
          "isDefault": true
        }
      ]
    }
  }
]'

Note the following:

instrumentEventId is a free text field that must uniquely identify this event in the corporate action source.
The instrumentIdentifiers field uses a LUID to resolve to the correct bond instrument in the LUSID Security Master, but you can specify any unique identifier.
The participationType must be Voluntary.
The effectiveDate is the date to redeem. Note this field is mandatory.
The pricePerUnit should be the market price of the redeemed bond expressed as a percentage of par and divided by 100, so 1.01 for a price of 101 and 0.98 for a price of 98. In future, you should be able to enter a market price without dividing.
You can set redemptionPercentage to a number between 0 and 1 representing a percentage to redeem. If you omit this field it defaults to 1 (or 100%) and the entire holding is redeemed.
You can set accruedInterestPerUnit to a fixed amount but the recommended approach is to omit this field and let LUSID calculate the interest accrued since the last coupon for you.
The earlyRedemptionElection object is mandatory, though has no effect in most circumstances. Typically you can specify a single election with any electionKey and make it both the chosen and default election.

Examining the impact of an `EarlyRedemptionEvent`

Consider this example of a bond with a face value of 7,500,000 bought at a premium of 102. If we examine holdings on the purchase settlement date, we see we have:

A bond holding for 7,500,000 units
A negative cash holding of £-7,664,023.97 representing the cost of purchasing the bond (plus accrued interest) at the premium:

The bond has annual coupon payments on 22 October each year from 2020 until 2026, and a principal repayment on the maturity date, 22 October 2026. LUSID would normally generate the following output transactions in response to instrument events emitted for this bond:

If we load an EarlyRedemptionEvent for 26 June 2025 at a strike price of 101, we see that:

LUSID no longer generates transactions representing the coupon payments on 22 October 2025 and 22 October 2026, nor the principal repayment nor maturity transactions.
Instead, LUSID generates one transaction representing interest accrued between 22 October 2024 and 10 June 2025, and a second representing a ‘sale’ of the bond at the strike price:

If we examine holdings again on 26 June 2025, we see that:

The bond holding has been removed.
Using sub-holding keys, separate cash holdings represent (in order) the cost of the original bond purchase, coupon payments up to 22 October 2024, accrued interest since 22 October 2024, and principal repayment at the strike price: