Loading an event instruction into a portfolio to configure event behaviour

  • Updated on Jun 13, 2025
  • Published on Aug 20, 2024
Prev Next

An event instruction is a mechanism for configuring the behaviour of a single instance of a specific instrument event in a particular portfolio. Note this event can either be an instrument lifecycle event or a corporate action event.

Depending on the type of instrument event, you can:

  • Ignore the event.

  • Configure the event for the entire portfolio; that is, for all holdings in the target instrument. Note you may have multiple holdings in the same instrument if you are using sub-holding keys (SHKs).

  • Configure the event for a particular holding. Note this option enables more granular control, for example by changing the date or the number of units impacted. More information.

  • Trigger certain events that are not automatically emitted by LUSID, such as option exercise events.

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 cash 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 specific instrumentEventId to configure, for example LUID_00003DV6-2024-02-06:

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

  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"
  }
}'
    JSON

    Note the following:

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

    • The instrumentEventId is the specific instrument event to configure, in this case LUID_00003DV6-2024-02-06.

    • 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 should 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:

For certain instrument events you can exert more granular control. For example, you could load an event instruction to:

  • Configure a CashDividendEvent for an Equity instrument to take a percentage in one currency and the remainder in another. See below.

  • Trigger LUSID to emit OptionExerciseCashEvent for an American ExchangeTradedOption instrument and exercise early. See an example.

Note: You must choose ElectForHolding and provide a holdingId to exercise more granular control.

Consider a variation on the event instruction for Portfolio C above, where this time we choose to take 75% in USD and the remainder in GBP:

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": "ElectForHolding",
    "holdingId": 68123148,
    "electionKey": "USD",
    "quantityInstructed": {
      "type": "Percentage",
      "amount": 75
    }
  }
}'
JSON

Note the following:

  • The instructionType is now ElectForHolding instead of ElectForPortfolio, and a holdingId is provided.

  • The quantityinstructed.type field is Percentage (between 1 and 100). It could be Units, but note there is no validation on the quantityInstructed.amount field, so it is possible to impact more units than you own, with unintended results.

Now on the ex-dividend date, LUSID generates output transactions in Portfolio C that result in a USD holding representing a dividend for 75% of the Microsoft shares, with the remainder defaulting to GBP at an exchange rate of 0.8: