How do I create a tax rule set and add tax rules?

  • Updated on Jul 31, 2025
  • Published on Aug 20, 2024
Prev Next

You can create a tax rule set specifying rates for a particular tax, for example dividend tax. You can then register the tax rule set with any number of portfolios and trigger LUSID to automatically calculate and store amounts of tax due for transactions in those portfolios that match the tax rules.

Consider the following example, of a call to the CreateTaxRuleSet API to create a tax rule set with two tax rules specifying UK and US dividend tax rates effective 1 January 2023: 

curl -X POST 'https://<your-domain>.lusid.com/api/api/tax/rulesets?effectiveAt=2023-01-01'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "id": {
    "scope": "DividendTax",
    "code": "UK-US-Equities"
  },
  "displayName": "Dividend tax",
  "description": "Dividend tax rates for US and UK equities",
  "outputPropertyKey": "Transaction/DividendTax/AmountDue",
  "rules": [
    {
      "name": "UKDividendTaxRule",
      "description": "Rule for the UK dividend tax rate",
      "rate": 0.25,
      "matchCriteria": [
        {
          "propertyKey": "Instrument/DividendTax/Domicile",
          "value": "UK",
          "criterionType": "PropertyValueEquals"
        },
        {
          "propertyKey": "Portfolio/DividendTax/Domicile",
          "value": "GB",
          "criterionType": "PropertyValueEquals"
        }
      ]
    },
    {
      "name": "USDividendTaxRule",
      "description": "Rule for the US dividend tax rate",
      "rate": 0.10,
      "matchCriteria": [
        {
          "propertyKey": "Instrument/DividendTax/Domicile",
          "value": "USA",
          "criterionType": "PropertyValueEquals"
        },
        {
          "propertyKey": "Portfolio/DividendTax/Domicile",
          "value": "GB",
          "criterionType": "PropertyValueEquals"
        }
      ]
    }
  ]
}'

Note the following:

  • The ‘start’ date of the tax rules in the set is specified using the effectiveAt query parameter in the URL.

  • The scope of the tax rule set must be registered with each portfolio you wish the tax rules to apply to.

  • The outputPropertyKey must reference the 3-stage key of a property in the Transaction domain that stores the calculated tax amount due for each matching transaction. You cannot subsequently change this key. It must be unique among all tax rule sets in the scope.

With this tax rule set in place, and once triggered for a particular portfolio, LUSID:

  • Does not calculate dividend tax for transactions upserted with a trade date or 31 December 2022 23:59:59 or earlier, even if they match the tax rules.

  • Calculates dividend tax for transactions upserted with a trade date of 1 January 2023 00:00:00 or later at the specified rates until such time as the tax rule set is updated with new rates, for example for the 2024 tax year.

For an example of how to trigger LUSID to apply this tax rule set and calculate dividend tax, see this tutorial.