--- title: "Using calendars in LUSID" slug: "using-calendars-in-lusid" updated: 2026-02-24T09:12:36Z published: 2026-02-24T09:12:36Z canonical: "support.lusid.com/using-calendars-in-lusid" --- > ## 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. # Using calendars in LUSID A *calendar* in LUSID is a repository of market holiday data that can contain: - All the holiday dates in a particular jurisdiction for as many years as data is provided for, for example a GBP calendar containing all UK public holidays for the next 30 years. - The days of the week that constitute the weekend in that jurisdiction, for example Saturday and Sunday. LUSID then infers that any date not in the calendar, or not at the weekend, is a good business day. There are several ways to create calendars in LUSID: - Subscribe to FINBOURNE's [Copp Clark](/v1/docs/copp-clark) integration to access ready-made calendars containing the latest market holiday data. - Use the APIs in the `Calendars` collection to create and populate your own calendars. [See an example](/v1/docs/using-calendars-in-lusid#creating-your-own-calendar-using-the-lusid-api). - Use [dedicated Luminesce providers](/v1/docs/readwrite-lusid-investment-data-lusid#scopes-transaction-types-cut-labels-and-calendars) to create and populate your own calendars. - Use the dashboard in the LUSID web app to manage your own calendars (coming soon). All calendars in LUSID have a *scope* and a *code*. You can pass one or more calendar *codes* into various LUSID operations to cause those operations to occur only on business days. See the examples in this article below. By default, calendar codes are selected from the scope `CoppClarkHolidayCalendars`. This is specified in the recipe you use for an operation. [See how to use calendars from a different scope](/v1/docs/using-calendars-in-lusid#changing-calendar-scope-in-a-recipe). ## Using calendars to distribute cashflows on business days You can specify `paymentCalendars` when modelling instruments that take a `flowConventions` object in their economic definition to factor in market holidays when performing certain operations, such as distributing cashflows. > **Note**: You can currently specify calendars for the following instrument types: `Bond`, `ComplexBond`, `InterestRateSwap`, `CreditDefaultSwap`, `FixedLeg`, `FloatingLeg`, `TermDeposit`, `EquitySwap`, `CapFloor`, `CdsIndex`, `FundingLeg`, `InflationLinkedBond`, `InflationSwap`. Consider the example of a [UK government bond](/v1/docs/modelling-fixed-rate-vanilla-bonds-in-lusid) that generates cashflows until expiry. The bond might have an economic definition with a `startDate` of 1 January 2022 and an annual `paymentFrequency`, meaning all cashflows until 2052 (annual coupon payments and the final principal repayment) are scheduled for distribution on a UK public holiday. You can specify: - A `rollconvention` to determine the day a payment occurs. - A `businessDayConvention` to determine what happens if the scheduled day falls on a non-business day. - Calendar code(s) in `paymentCalendars` to determine good business days in appropriate jurisdiction(s). If more than one calendar code is specified, holidays for all the specified calendars are applied. Note calendar codes must exist in the [calendar scope specified in a recipe](/v1/docs/using-calendars-in-lusid#changing-calendar-scope-in-a-recipe). [More about roll conventions and business day conventions](/v1/docs/roll-conventions-and-business-day-conventions). For example: ```json curl -X POST "https://.lusid.com/api/api/instruments"  -H "Authorization: Bearer "  -H "Content-Type: application/json"  -d '{"upsert-request-1": {    "name": "T 3 01/01/52",    "identifiers": {      "ClientInternal": {"value": "T_3_01/01/52"}      },    "definition": {      "instrumentType": "Bond",      "startDate": "2022-01-01T10:00:00.0000000+00:00",      "maturityDate": "2052-01-01T10:00:00.0000000+00:00",      "identifiers": {},      "flowConventions": {        "currency": "GBP",        "paymentFrequency": "1Y",        "dayCountConvention": "Act365",        "paymentCalendars": ["GBP"],        "rollConvention": "1",        "resetCalendars": [],        "resetDays": 0,        "businessDayConvention": "ModifiedFollowing"      },      "domCcy": "GBP",      "couponRate": 0.015,      "principal": 1    }  } }' ``` LUSID has numerous tools to manage cashflows. For example, you can call the [GetUpsertablePortfolioCashFlows](https://www.lusid.com/docs/api#operation/GetUpsertablePortfolioCashFlows) API for a transaction portfolio containing this example of a 2052 UK government bond to retrieve expected cashflows between 2045 and 2052 in a format ready-to-upsert into LUSID: ```json curl -X GET "https://.lusid.com/api/api/transactionportfolios///upsertablecashflows?effectiveAt=2022-01-01T10%3A00%3A00Z&windowStart=2045-01-01T10%3A00%3A00Z&windowEnd=2053-01-01T10%3A00%3A00Z&excludeUnsettledTrades=true"  -H "Authorization: Bearer " ``` Note the following: - Most years, cashflows are distributed on 2 January, which is the next available business day. - Some years, when the UK public holiday falls on a Friday, Saturday or Sunday, cashflows are distributed on subsequent days instead: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/9f63d4aa-bad3-41b3-9500-fdca047d421b.png) ## Using calendars to perform valuations on business days When you [perform a valuation](/v1/docs/how-do-i-perform-a-valuation) you can specify a schedule encompassing a range of dates. LUSID then produces a separate report for each weekday in the range (by default, [Saturdays and Sundays](/v1/docs/scheduling-a-valuation#performing-a-valuation-at-the-weekend) are omitted). To factor market holidays into your valuation schedule, or to perform a valuation at the weekend, call the `GetValuation` API and specify a `valuationSchedule` object with `effectiveFrom` and `effectiveAt` dates. [See how to do this](/v1/docs/scheduling-a-valuation). > **Note:** The operation only adjusts dates according to calendar data if you are valuing across a *range* of dates. If you only specify a single `effectiveAt` date, the operation produces a valuation for that exact date, regardless of whether the date is a good business day or not. Consider the following example of factoring in market holidays when valuing [this multi-asset, multi-region portfolio](/v1/docs/valuing-a-multi-asset-multi-region-portfolio) between 2 January 2023 (a UK public holiday) and 5 January 2023: ```json curl -X POST "https://.lusid.com/api/api/aggregation/$valuation"  -H "Authorization: Bearer "  -H "Content-Type: application/json-patch+json"  -d '{    "portfolioEntityIds": [      {"scope": "my-portfolio-scope", "code": "my-portfolio-code"}    ],    "recipeId": {"scope": "my-recipe-scope", "code": "my-recipe-code"},    "valuationSchedule": {      "effectiveFrom": "2023-01-02T00:00:00.0000000+00:00",      "effectiveAt": "2023-01-05T00:00:00.0000000+00:00",      "rollConvention": "ModifiedFollowing",      "holidayCalendars": ["GBP"]    },    "metrics": [      {"key": "Valuation/EffectiveAt", "op": "Value"},      {"key": "Holding/Cost/Pfolio", "op": "Sum"},      {"key": "Valuation/PvInPortfolioCcy", "op": "Sum"},      {"key": "Valuation/PnL/Unrealised/PfolioCcy", "op": "Sum"}    ],    "groupBy": ["Valuation/EffectiveAt"]  }' ``` *Without* specifying any `holidayCalendars`, the daily valuation looks like this, with all dates listed… ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/f1428bae-f7c7-4c13-acbb-0d0aef8f056e.png) …but *with* `holidayCalendars` specified, the operation accounts for the UK public holiday on 2 January 2023 and only returns a daily valuation for good business days: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/e2eebe6e-de09-4aff-a220-52b6d6134b73.png) ## Changing calendar scope in a recipe To select calendars from a scope other than the default `CoppClarkHolidayCalendars`, you will need to change the [recipe](/v1/docs/how-do-i-create-or-generate-a-recipe) you are using for an operation. To do this, specify the `market.options.calendarScope` field. Note you also have to set the `market.options.defaultScope` field whenever you change a market option, but you can just reset this to the default value of `default`, for example: ```json curl -X POST "https://.lusid.com/api/api/recipes" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{  "configurationRecipe": {    "scope": "my-recipe-scope",    "code": "my-recipe-code",    "market": {      "marketRules": [        {          "key": "Quote.Figi.*",          "supplier": "Lusid",          "dataScope": "MyQuoteScope",          "quoteType": "Price",          "field": "Mid",          "sourceSystem": "Lusid"        }      ],      "options": {        "defaultScope": "default",        "calendarScope": "my-own-calendar-scope",      },    },    "description": "A recipe set to use calendars from a source other than Copp Clark",  } }' ``` ## Creating your own calendar using the LUSID API As an example, we’ll create a calendar that considers every day of the year a good business day except the last day of each quarter. To get started, call the [CreateCalendar](https://www.lusid.com/docs/api/lusid/endpoints/calendars/CreateCalendar/) API to create an empty calendar. Note `weekendMask.days` is set to empty to include Saturday and Sunday as good business days: ```json curl -X POST 'https://.lusid.com/api/api/calendars/generic'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "calendarId": {    "scope": "MyCalendars",    "code": "LastDayOfEachQuarter"  },  "calendarType": "Holiday",  "weekendMask": {    "days": [],    "timeZone": "UTC"  },  "sourceProvider": "Hand-crafted-calendar" }' ``` Call the [BatchUpsertDatesToCalendar](https://www.lusid.com/docs/api/lusid/endpoints/calendars/BatchUpsertDatesForCalendar) API to load holiday dates into the calendar: - The scope and code of the target calendar are specified in the URL. - The `fromUtc` and `toUtc` fields must contain UTC datetimes representing the start and end of the holiday. Note the `toUtc` field is exclusive, so specify midnight at the start of the *following* day to declare the full 24 hours of the required day as a holiday. For example, to nominate 15 January 2026: - In the UTC timezone, specify midnight (15 Jan) to midnight (16 Jan): `2026-01-15T00:00:00Z` to `2026-01-16T00:00:00Z` - In the EST timezone (5 hours behind UTC), specify 5am (15 Jan) to 5am (16 Jan): `2026-01-15T05:00:00Z` to `2026-01-16T05:00:00Z` - In the CET timezone (1 hour ahead of UTC), specify 11pm (*the previous day*, 14 Jan) to 11pm (15 Jan): `2026-01-14T23:00:00Z` to `2026-01-15T23:00:00Z` - The `timeZone` field is not used by LUSID, so we recommend specifying `UTC` as other IANA [TZ identifiers](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) may fail. - We recommend checking the `failed` object in the response for rejected holidays. ```json curl -X POST 'https://.lusid.com/api/api/calendars/generic/MyCalendars/LastDayOfEachQuarter/dates/$batchUpsert?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "LastDayOfFirstQuarter": {    "dateId": "LastDayOfFirstQuarter",    "fromUtc": "2026-03-31T00:00:00Z",    "toUtc": "2026-04-01T00:00:00Z",    "timeZone": "UTC",    "description": "Last day of first quarter 2026",  },  "LastDayOfSecondQuarter": {    "dateId": "LastDayOfSecondQuarter",    "fromUtc": "2026-06-30T00:00:00Z",    "toUtc": "2026-07-01T00:00:00Z",    "timeZone": "UTC",    "description": "Last day of second quarter 2026",  },  "LastDayOfThirdQuarter": {    "dateId": "LastDayOfThirdQuarter",    "fromUtc": "2026-09-30T00:00:00Z",    "toUtc": "2026-10-01T00:00:00Z",    "timeZone": "UTC",    "description": "Last day of third quarter 2026",  },  "LastDayOfFourthdQuarter": {    "dateId": "LastDayOfFourthdQuarter",    "fromUtc": "2026-12-31T00:00:00Z",    "toUtc": "2027-01-01T00:00:00Z",    "timeZone": "UTC",    "description": "Last day of fourth quarter 2026",  } }' ``` We can now call the: - [GetDates](https://www.lusid.com/docs/api/lusid/endpoints/calendars/GetDates) API to list the holiday dates loaded into the calendar. - [IsBusinessDateTime](https://www.lusid.com/docs/api/lusid/endpoints/calendars/IsBusinessDateTime) API to test whether a particular date is a good business day or not according to this calendar. - [GenerateSchedule](https://www.lusid.com/docs/api/lusid/endpoints/calendars/GenerateSchedule) API to list the good business days on which a valuation will be performed if a range of days is specified (in this case, it will be every day except 31 March, 30 June, 30 September and 31 December).