--- title: "Adjusting times and delaying the impact of instrument events" slug: "adjusting-times-and-delaying-the-impact-of-instrument-events" updated: 2026-01-29T15:42:17Z published: 2026-01-29T15:42:17Z canonical: "support.lusid.com/adjusting-times-and-delaying-the-impact-of-instrument-events" --- > ## 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. # Adjusting times and delaying the impact of instrument events By default, LUSID emits [instrument lifecycle](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid) and [corporate action](/v1/docs/understanding-dedicated-corporate-action-events) events at UTC midnight, and so transactions automatically generated by these events impact portfolios at the same time. You can configure the definition of an [instrument](/v1/docs/instruments) to add some or all of the following: - A *primary timezone* so that events impacting that instrument are emitted at local midnight rather than UTC midnight. - A *start of day time* in that timezone so events are emitted at that time rather than local midnight, perhaps to account for daylight saving. - A *market open time* in that timezone so that transaction generation is delayed to impact portfolios when the market is open, and market data is available, rather than when events are emitted. > **Note**: If you do add timezone information to an instrument then make sure all other datetimes in the definition (for example, `startDate` and `maturityDate`) are expressed as local time translated to UTC. ## Example: Configuring the timing of a Microsoft cash dividend Consider a `CashDividendEvent` for an instrument of type `Equity` representing MSFT [similar to this one](/v1/docs/handling-a-cash-dividend-corporate-action-event). In this version, the mandatory ex-dividend and payment dates are modelled using [date stamps](/v1/docs/how-do-i-upload-corporate-actions-to-a-corporate-action-source#specifying-datetimes-for-corporate-actions) instead of the `exDate` and `paymentDate` datetime fields: ```json {  "instrumentEventId": "MSCashDividend-2024-02-06",  "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},  "description": "Cash dividend of 20 cents per share",  "participationType": "MandatoryWithChoices",  "eventDateStamps": {    "exDate": {      "day": 6,      "month": 2,      "year": 2024    },    "paymentDate": {      "day": 10,      "month": 2,      "year": 2024    },  },  "instrumentEvent": {    "instrumentEventType": "CashDividendEvent",    ... ``` Since no explicit time or timezone information can be specified for date stamps, and the datetime fields themselves are omitted, LUSID: - Emits the `CashDividendEvent` on 6 February 2024 at UTC midnight. - Generates a transaction representing the dividend payment amount with a: - Transaction date of the `exDate`: 6 February 2024 at UTC midnight. - Settlement date of the `paymentDate`: 10 February at UTC midnight. > **Note**: If you specify both date stamps *and* corresponding datetime fields, the latter are preferred. Let’s imagine we want to change this to: - Emit the event in the New York timezone rather than UTC. - Set the start of day in New York to be 1am local time instead of midnight. - Set the market open time to be 9:30am local time. ### Step 1: Specifying temporal information in the instrument definition We can call the [UpsertInstruments](https://www.lusid.com/docs/api/lusid/endpoints/instruments/UpsertInstruments) API to add a `timeZoneConventions` object to the `Equity` instrument representing MSFT: ```json curl -X POST 'https://.lusid.com/api/api/instruments'   -H 'Authorization: Bearer '   -H 'Content-Type: application/json-patch+json'   -d '{"upsert-request-1": {    "name": "MSFT",    "identifiers": {"Figi": {"value": "BBG000BPH459"}},    "definition": {      "instrumentType": "Equity",      "domCcy": "GBP",      "timeZoneConventions": {        "primaryTimeZone": "America/New_York",        "startOfDay": "NY_SOD",        "primaryMarketOpen": "NY_Open"      }    }  } }' ``` Note the following: - The `primaryTimeZone` field is mandatory. It accepts any [IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - The `startOfDay` field is optional and accepts the code of a [cut label definition](/v1/docs/what-is-a-cut-label) in the same timezone. - The `primaryMarketOpen` field is optional and accepts the code of a cut label definition in the same timezone. Note [further configuration](/v1/docs/adjusting-times-and-delaying-the-impact-of-instrument-events#step-3-delaying-transaction-generation-until-market-open-time) is required to actually generate transactions at this time. ### Step 2: Examining resolved datetimes for the corporate action We can call the [GetInstrumentEvents](https://www.lusid.com/docs/api/lusid/endpoints/corporate-action-sources/GetInstrumentEvents/) API to examine the time and timezone information resolved for this `CashDividendEvent` from the MSFT instrument definition: ```json {  "values": [    {      "instrumentEventId": "MSCashDividend-2024-02-06",      "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},      "description": "Cash dividend of 20 cents per share",      "participationType": "MandatoryWithChoices",      "completeness": "Complete",      "instrumentEvent": {        "exDate": "2024-02-06T06:00:00+00:00",        "paymentDate": "2024-02-10T06:00:00+00:00",        ... ``` Since LUSID stores all datetimes in UTC (and does not persist date stamps): - The resolved `exDate` is stored as 6 February 2024 at 6am in the UTC timezone. - The resolved `paymentDate` is stored as 10 February 2024 at 6am in the UTC timezone. New York is five hours behind UTC but note the UTC time has been adjusted by one hour to reflect the `startOfDay` in the instrument definition. ### Step 3: Delaying transaction generation until market open time To delay the timestamp of the transaction generated by `CashDividendEvent` until the market is open, further configuration is required. We must 1. [Create a custom transaction template](/v1/docs/how-do-i-create-a-custom-transaction-template) for `CashDividendEvent` in a particular template scope to override the default template provided by FINBOURNE, keeping all the original settings. 2. Add a `marketOpenTimeAdjustments` object with a list of datetime fields to delay until the `primaryMarketOpen` time in the instrument definition. Note that if the `exDate` timestamp is already later than the market open time, no action is taken. 3. Register the custom transaction template scope with the parent portfolio. Note you can [patch an existing portfolio](/v1/docs/updating-certain-characteristics-of-an-existing-portfolio). For example, we can call the [CreateTransactionTemplate](https://www.lusid.com/docs/api/lusid/endpoints/instrument-event-types/CreateTransactionTemplate) API as follows to delay both the `exDate` and `paymentDate` fields (we could choose to delay just one of these): ```json curl -X POST 'https://.lusid.com/api/api/instrumenteventtypes/CashDividendEvent/transactiontemplates/Equity/MyTransactionTemplates'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{   "description": "My template for overriding the FBN-provided default cash dividend transaction template",   "componentTransactions": [    {      "displayName": "Dividend Income",      "transactionFieldMap": {        "transactionId": "{{instrumentEventId}}-{{holdingId}}",        "type": "DividendIncome",        "source": "default",        "instrument": "{{instrument}}",        "transactionDate": "{{CashDividendEvent.exDate}}",        "settlementDate": "{{CashDividendEvent.paymentDate}}",        "units": "{{eligibleBalance}}",        "transactionPrice": {          "price": "{{CashDividendEvent.DeclaredElection.dividendRate}}",          "type": "CashFlowPerUnit"        },        "transactionCurrency": "{{CashDividendEvent.DeclaredElection.dividendCurrency}}",        "exchangeRate": "{{CashDividendEvent.ChosenElection.exchangeRate}}",        "totalConsideration": {          "currency": "{{CashDividendEvent.ChosenElection.dividendCurrency}}",          "amount": "{{CashDividendEvent.ChosenElection.dividendAmount}}"        }      },      "transactionPropertyMap": [],      "marketOpenTimeAdjustments": [        "CashDividendEvent.exDate",        "CashDividendEvent.paymentDate"      ]    }   ] }' ``` ### Step 4: Examining datetimes for events and generated transactions We can call the [QueryApplicableInstrumentEvents](https://www.lusid.com/docs/api/lusid/endpoints/instrument-events/QueryApplicableInstrumentEvents/) API for the parent portfolio to examine the `CashDividendEvent` and its impact: ```json {  "values": [    {      "instrumentType": "Equity",      "instrumentEventType": "CashDividendEvent",      "instrumentEventId": "BBG000BPH459-2024-02-06",      "loadedEvent": {        "description": "BBG000BPH459-2024-02-06",        "completeness": "Complete",        "instrumentEvent": {          "exDate": "2024-02-06T06:00:00+00:00",          "paymentDate": "2024-02-10T06:00:00+00:00",        },        "participationType": "MandatoryWithChoices",        ...      },      "transactions": [        {          "transactionDate": "2024-02-06T14:30:00.0000000+00:00",          "settlementDate": "2024-02-10T14:30:00.0000000+00:00",          "units": 1000,          "transactionPrice": {            "price": 0.2,            "type": "CashFlowPerUnit"          },          "totalConsideration": {            "amount": 160,            "currency": "GBP"          },          "exchangeRate": 0.8,          "transactionCurrency": "USD",          "resolvedTransactionTypeDetails": {            "scope": "default",            "source": "default",            "type": "DividendIncome"          },          ...        }      ]    }  ],  ... } ``` Note the following: - In the `loadedEvent.InstrumentEvent` object, the `exDate` and `paymentDate` fields reveal that LUSID emits the event at 6am in the UTC timezone (1am in New York): - In the `transactions` object, the `transactionDate` and `settlementDate` fields reveal that LUSID delays transaction generation until 2:30pm in the UTC timezone (9:30am in New York).