Flow conventions and index conventions

When mastering certain types of instrument in LUSID, you must specify rules for payments arising during the lifetime of those instruments:

Specifying a flow convention

A flow convention determines the payment schedule for a set of cashflows.

Consider the following example of a schedule that pays twice yearly on the 22nd, rescheduling to the next good business day if this is a holiday in the UK:

{
  "currency": "GBP",
  "paymentFrequency": "6M",
  "dayCountConvention": "Actual365",
  "rollConvention": "22",
  "businessDayConvention": "Following",
  "paymentCalendars": ["GBP"],
  "resetCalendars": ["GBP"]
}

For information on all fields, examine the FlowConventions schema. Note in particular the following:

• paymentFrequency can be any tenor determining the number of interest rate periods per year, in this case 6M specifying two periods.

• The dayCountConvention methodology determines the number of days in a period.

• rollConvention specifies the payment day of the month. For a bond, this should count back from maturity, so in this case 22 for a bond maturing on 22 October, which means the coupon dates are 22 October and 22 April each year. We also recommend setting a businessDayConvention to determine what should happen if this is not a good business day. More information on roll and business day conventions.

• paymentCalendars and resetCalendars  both accept codes of one or more holiday calendars to determine good business days, for example ["GBP","LON"]. Note the scope of holiday calendars is defined in a recipe.

• accrualDateAdjustment defaults to Adjusted. This is suitable for European treasury bonds but for US treasury bonds we recommend Unadjusted.

• settleDays is deprecated, and resetDays is ignored for bond fixed schedules. The scope and code fields can be ignored unless you are loading a flow convention from a library.

Specifying a CDS flow convention

A CDS flow convention determines the payment schedule for credit default swap instruments. This is represented in LUSID by a CdsFlowConventions object that is similar, though not identical, to FlowConventions.

Specifying an index convention

An index convention derives the calculation of payment amounts from interbank lending rates or similar.

{
  "fixingReference": "GBP1YBMK",
  "publicationDayLag": 1,
  "paymentTenor": "12M",
  "dayCountConvention": "ActActIsma",
  "currency": "GBP"
}

For information on all fields, examine the IndexConvention schema. Note in particular the following:

• fixingReference should be an intuitive string that enables LUSID to look up fixings in the Quote Store each time an accrued interest calculation is required.

• paymentTenor must be a tenor specifying the length of the interest rate period, in this case 12M. For OIS, specify 1D.

• The dayCountConvention methodology determines the number of days in a period.

• indexName defaults to INDEX but you can change this to a more intuitive description, for example LIBOR or SOFR.

Specifying an inflation index convention

An inflation index convention derives the calculation of payments from an index such as UKRPI.

{
  "inflationIndexName": "UKRPI",
  "currency": "GBP",
  "observationLag": "3M"
}

For information on all fields, examine the InflationIndexConvention schema. Note in particular the following:

• The inflationIndexName should be an intuitive string that enables LUSID to look up fixings in the Quote Store each time an accrued interest calculation is required.

• The currency should be the same as the domCcy.

• The observationLag must be a tenor with a unit of M for months, for example 3M.

• The inflationFrequency defaults to a tenor of 1M but can be set to 3M for Australian or NZ bonds, in which case the flow convention paymentFrequency must also be set to 3M.

Specifying convention objects inline

While it is possible to specify convention objects once and load them from a library, the recommended approach is to specify each object ‘inline’ within the economic definition; that is, create a bespoke convention object at the same time as you master that instrument.

Consider the following example of a call to the UpsertInstruments API to master a floating schedule complex bond:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
-H "Authorization: Bearer <your-API-access-token>"
-H "Content-Type: application/json"
-d '{ "bond-upsert-1": {
        "name": "NWG 3 1/8 03/28/27",
        "identifiers": {"ClientInternal": {"value": "XS1970533219"}},
        "definition": {
            "instrumentType": "ComplexBond",
            "schedules": [
                {
                    "scheduleType": "Float",
                    "startDate": "2026-03-28T00:00:00+00:00",
                    "maturityDate": "2027-03-28T00:00:00+00:00",
                    "flowConventions": {
                        "currency": "GBP",
                        "paymentFrequency": "12M",
                        "dayCountConvention": "ActActIcma",
                        "rollConvention": "None",
                        "paymentCalendars": ["GBP","LON"],
                        "resetCalendars": ["GBP","LON"],
                        "settleDays": 2,
                        "resetDays": 2,
                        "leapDaysIncluded": true
                    },
                    "notional": 1000000.0,
                    "paymentCurrency": "GBP",
                    "stubType": "ShortFront",
                    "spread": "0.0",
                    "indexConventions": {
                        "currency": "GBP",
                        "code": "GBP1YSWO",
                        "paymentTenor": "12M",
                        "dayCountConvention": "ActActIcma",
                        "fixingReference": "GBP1YSWO",
                        "publicationDayLag": 0,
                        "IndexName": "GBP1YSWO"
                    }
                }
            ]
        }
    }
}'