--- title: "Loading an event instruction into a portfolio to configure event behaviour" slug: "loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio" updated: 2026-03-24T14:09:52Z published: 2026-03-24T14:09:52Z canonical: "support.lusid.com/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # Loading an event instruction into a portfolio to configure event behaviour 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](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid) or a [corporate action event](/v1/docs/understanding-dedicated-corporate-action-events). 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](/v1/docs/what-is-a-sub-holding-key-shk) (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](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio#changing-the-date-or-number-of-units-impacted). - Trigger certain events that are not automatically emitted by LUSID, such as option exercise events. [More information](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio#changing-the-date-or-number-of-units-impacted). ## Example: Configuring the behaviour of a `CashDividendEvent` corporate action 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](/v1/docs/handling-a-cash-dividend-corporate-action-event#uploading-a-corporate-action-to-the-source) 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/EventInstructions1.png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A21%3A32Z&se=2026-11-04T03%3A21%3A32Z&sr=c&sp=r&sig=oD8HTmvlUiiVbhLZOz1qeQSKs8Yl5T7vsIQ7ZELhLNE%3D) By default on the ex-dividend date, LUSID generates output transactions in all three portfolios that result in the following GBP cash holdings: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/EventInstructions2.png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A21%3A32Z&se=2026-11-04T03%3A21%3A32Z&sr=c&sp=r&sig=oD8HTmvlUiiVbhLZOz1qeQSKs8Yl5T7vsIQ7ZELhLNE%3D) 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](https://www.lusid.com/docs/api#operation/QueryApplicableInstrumentEvents) API for portfolio C to determine the specific `instrumentEventId` to configure, for example `LUID_00003DV6-2024-02-06`: ```json {  "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](https://www.lusid.com/docs/api#operation/UpsertInstrumentEventInstructions) API to load a suitable event instruction into Portfolio C, for example: ```json curl -X POST 'https://.lusid.com/api/api/portfolios/UKEquities/PortfolioC/instrumenteventinstructions?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "request": {    "instrumentEventInstructionId": "MsftCashDividendOverrideFeb2024",    "instrumentEventId": "LUID_00003DV6-2024-02-06",    "instructionType": "ElectForPortfolio",    "electionKey": "USD"  } }' ``` 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/EventInstructions3.png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A21%3A32Z&se=2026-11-04T03%3A21%3A32Z&sr=c&sp=r&sig=oD8HTmvlUiiVbhLZOz1qeQSKs8Yl5T7vsIQ7ZELhLNE%3D) [More on multiple cash elections](/v1/docs/understanding-participation-types-and-elections-for-corporate-actions#specifying-multiple-cash-elections). ## Changing the date or number of units impacted 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](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments#loading-an-event-instruction-to-trigger-optionexercisecashevent). > **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](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio#example-configuring-the-behaviour-of-a-cashdividendevent-corporate-action), where this time we choose to take 75% in USD and the remainder in GBP: ```json curl -X POST 'https://.lusid.com/api/api/portfolios/UKEquities/PortfolioC/instrumenteventinstructions?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "request": {    "instrumentEventInstructionId": "MsftCashDividendOverrideFeb2024",    "instrumentEventId": "LUID_00003DV6-2024-02-06",    "instructionType": "ElectForHolding",    "holdingId": 68123148,    "electionKey": "USD",    "quantityInstructed": {      "type": "Percentage",      "amount": 75    }  } }' ``` 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/EventInstructionQuantity.png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A21%3A32Z&se=2026-11-04T03%3A21%3A32Z&sr=c&sp=r&sig=oD8HTmvlUiiVbhLZOz1qeQSKs8Yl5T7vsIQ7ZELhLNE%3D)