---
title: "How do I create a tax rule set and add tax rules?"
slug: "how-do-i-create-a-tax-rule-set-and-add-tax-rules"
updated: 2025-07-31T14:48:37Z
published: 2025-07-31T14:48:37Z
canonical: "support.lusid.com/how-do-i-create-a-tax-rule-set-and-add-tax-rules"
---

> ## 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.

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

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](https://www.lusid.com/docs/api#operation/CreateTaxRuleSet) API to create a tax rule set with two tax rules specifying UK and US dividend tax rates effective 1 January 2023:

```json
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](/v1/docs/how-do-i-create-a-transaction-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](https://www.lusid.com/docs/api/lusid/endpoints/tax-rule-sets/UpdateTaxRuleSet) 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](/v1/docs/calculating-dividend-tax-and-reporting-it-as-a-separate-cash-balance).