Loading an event instruction to override an instrument event for a particular portfolio

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 USD 0.2 per share 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: