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:That is subscribed to the corporate action source into which the corporate action event is loaded.
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:
![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/259b6ed5-abaa-42f0-bf31-b6245b6edd8f.png)
By default on the ex-dividend date, LUSID generates output transactions in all three portfolios that result in the following GBP holdings:
![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/8727add5-9eca-4fd8-a781-cc3e403d882f.png)
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:
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" ...
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
isElectForPortfolio
to impact every Microsoft holding in portfolio C (in circumstances where there is more than one). Alternative values areIgnore
andElectForHolding
; note the latter requires aholdingId
to identify which Microsoft holding to override.For
ElectForPortfolio
andElectForHolding
, theelectionKey
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:
![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/fc17b3d6-5d9b-420e-9aff-df83bffc9e73.png)