By default, an instrument event impacts every holding in the underlying instrument in every applicable portfolio:

• For an instrument lifecycle event such as BondCouponEvent, this is every portfolio with a holding in the underlying instrument.

• For a corporate action event such as CashDividendEvent, this is every portfolio:

  1. That is subscribed to the corporate action source into which the corporate action event is loaded.

  2. With a holding in the underlying instrument.

Note: You might have more than one holding in the same underlying instrument in a portfolio if you are using sub-holding keys (SHKs).

You can override this for a particular portfolio by loading an event instruction into that portfolio:

• You can choose to ignore the event entirely.

• For a corporate action event with elective choices such as CashDividendEvent:

  • You can choose a different election for all holdings in the underlying instrument in the portfolio.

  • You can choose a different election for a particular holding in the portfolio.

Consider a scenario where we have:

• Three portfolios subscribed to a corporate action source. Each portfolio has a holding of 1000 Microsoft shares.

• A CashDividendEvent corporate action like this one loaded into the corporate action source that declares a dividend of 10% in USD but elects to take it in GBP at an exchange rate of 0.8:

By default on the ex-dividend date, LUSID generates output transactions in all three portfolios that result in the following GBP holdings:

We can change this just for Portfolio C by loading an event instruction to take the dividend in the original USD currency instead. To do this:

1. Call the QueryApplicableInstrumentEvents API for portfolio C to determine the ID of the instrument event to override. The response might be as follows:

   {
     "values": [
       {
         "portfolioId": {"scope": "UKEquities", "code": "PortfolioC"},
         "holdingId": 68123148,
         "lusidInstrumentId": "LUID_00003DV6",
         "instrumentScope": "default",
         "instrumentType": "Equity",
         "instrumentEventType": "CashDividendEvent",
         "instrumentEventId": "LUID_00003DV6-2024-02-06"
         ...

2. Call the UpsertInstrumentEventInstructions API to load a suitable event instruction into Portfolio C, for example:

   curl -X POST 'https://<your-domain>.lusid.com/api/api/portfolios/UKEquities/PortfolioC/instrumenteventinstructions?successMode=Partial'
     -H 'Content-Type: application/json-patch+json'
     -H 'Authorization: Bearer <your-API-access-token>'
     -d '{
     "request": {
       "instrumentEventInstructionId": "MsftCashDividendOverrideFeb2024",
       "instrumentEventId": "LUID_00003DV6-2024-02-06",
       "instructionType": "ElectForPortfolio",
       "electionKey": "USD"
     }
   }'

   Note the following:

   • The InstrumentEventInstructionID must be unique among all the event instructions loaded into this portfolio.

   • The instrumentEventId is the ID of the instrument event to override.

   • The instructionType is ElectForPortfolio to impact every Microsoft holding in portfolio C (in circumstances where there is more than one). Alternative values are Ignore and ElectForHolding; note the latter requires a holdingId to identify which Microsoft holding to override.

   • For ElectForPortfolio and ElectForHolding, the electionKey must be the key of a cash election in the original instrument event to use instead.

Now on the ex-dividend date, LUSID generates output transactions that result in GBP holdings in Portfolios A and B but a USD holding in Portfolio C: