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

Providing you have appropriate access control permissions, you can create a tax rule set specifying rates for a particular tax, for example dividend tax. You can then trigger LUSID to automatically calculate and store amounts of tax due for transactions matching these tax rules.

Note: A tax rule set is a time-variant entity. The recommended approach is to create an empty tax rule set effective from a suitably early date, for example 1 January 2000. You can then update the tax rule set with rules (rates) for subsequent tax years. Note it is not possible to retrofill rates for tax years prior to the creation date of the entity (so in this scenario you could not load rates for the 1999 tax year).

Consider the following example, of a tax rule set created at the beginning of the millenium and updated with tax rules specifying UK and US dividend tax rates for the 2023 tax year:

1. Obtain an API access token.
2. Call the CreateTaxRuleSet API, specifying a suitably-early effective date in the URL (highlighted in red below) and, in the body of the request:
   • An outputPropertyKey referencing the 3-stage key of a property in the Transaction domain to store the calculated tax amount due for each matching transaction. You cannot subsequently change this key.
   • An empty rules collection (both highlighted in yellow):

   curl -X POST 'https://<your-domain>.lusid.com/api/api/tax/rulesets?effectiveAt=2000-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": []
   }'

3. Call the UpdateTaxRuleSet API to specify tax rules for the 2023 tax year, specifying:
   • In the URL, the scope and code of the tax rule set and a suitable effective date (highlighted in red below).
   • In the body of the request, one or more tax rules in the rules collection. Note the order in which tax rules are specified is significant; LUSID uses the first matching tax rule found for each transaction. Each tax rule must consist of:
     • A name that uniquely identifies the tax rule in the tax rule set, and a description.
     • A tax rate expressed as a decimal, for example 0.1 for 10%. 
     • One or more matchCriteria, all of which must be met for the tax rule to apply. The propertyKey can be the 3-stage key of any property in the Instrument, Portfolio or InstrumentEvent domain if criterionType is PropertyValueEquals or PropertyValueIn. The propertyKey can be the 3-stage key of any sub-holding key in the Transaction domain if criterionType is SubHoldingKeyValueEquals.
     Note you can update the displayName and description of the tax rule set but not the outputPropertyKey.

   For example:

   curl -X PUT 'https://<your-domain>.lusid.com/api/api/tax/rulesets/DividendTax/UK-US-Equities?effectiveAt=2023-01-01'
    -H 'Content-Type: application/json-patch+json'
    -H 'Authorization: Bearer <your-API-access-token>'
    -d '{
    "displayName": "Dividend tax 2023",
    "description": "Dividend tax rates for US and UK equities 2023",
    "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"
          }
        ]
      }
    ]
   }'

With this tax rule set in place, and once triggered, LUSID:

• Does not calculate dividend tax for transactions upserted with a trade date between 2000-01-01 and 2022-12-31, even if they match the tax rules.
• Calculates dividend tax for transactions upserted with a trade date on or after 2023-01-01 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.