Reporting withholding tax separately for cash dividend corporate actions

In this tutorial we'll see how to use LUSID to perform the following task:

As a portfolio manager, I want LUSID to automatically calculate the correct rate of withholding tax for cash dividend corporate actions in different jurisdictions, and report the tax due in different currencies as separate cash balances.

We'll see how to:

• Master instruments representing BP and Microsoft equities, each with a tax-related property that LUSID can use to determine the correct rate of withholding tax in different jurisdictions.
• Create a corporate action source and load corporate actions representing cash dividends for BP and Microsoft.
• Set up a UK-domiciled portfolio with holdings in BP and Microsoft, subscribe to the corporate action source, register a sub-holding key (SHK) to report withholding tax separately, and attach a tax-related property that LUSID can use to determine the correct rate of withholding tax, in conjunction with instrument properties (above).
• Create a tax rule set with rates for different jurisdictions that LUSID can use to automatically calculate and store the amount of withholding tax due for each cash dividend.
• Create a custom transaction type to override the default behavior and report the total amounts of withholding tax due as separate GBP and USD cash balances in a holdings report.

LUSID automatically applies the built-in Dividend transaction type to corporate actions representing cash dividends. This means that (positive) dividend payments and (negative) tax amounts impact main portfolio cash balances by default. Consider the following scenario:

Holding	Start # units	Dividend %	Dividend amount	WH tax %	WH tax amount	End # units
BP	100000	10%	£10000	25%	£2500	100000
GBP cash balance	20000	n/a				27500
Microsoft	100000	10%	$10000	10%	$1000	100000
USD cash balance	20000	n/a				29000

The intention of our custom transaction type is to override Dividend and report the tax amount due as separate cash balances:

Holding	Start # units	Dividend %	Dividend amount	WH tax %	WH tax amount	End # units
BP	100000	10%	£10000	25%	£2500	100000
GBP cash balance	20000	n/a				30000
GBP withholding tax	0	n/a				-2500
Microsoft	100000	10%	$10000	10%	$1000	100000
USD cash balance	20000	n/a				30000
USD withholding tax	0	n/a				-1000

• Section 1: Mastering instruments and attaching a tax-related property
• Section 2: Creating a corporate action source and loading corporate actions
• Section 3: Setting up a transaction portfolio and attaching a tax-related property
• Section 4: Creating a tax rule set to calculate different rates of withholding tax
• Section 5: Creating a custom transaction type to report withholding tax separately
• Section 6: Generating a holdings report
   

Mastering instruments and attaching a tax-related property

We can call the UpsertInstruments API to master BP and Microsoft as equity instruments in the LUSID Security Master. Note the GBP and USD currency instruments are pre-mastered.

At the same time, we can attach a tax-related custom property (with a 3-stage key of Instrument/Tax/Country) to each of BP and Microsoft to help LUSID determine the correct rate of withholding tax for cash dividends in different jurisdictions.

Step 1 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. You can execute the Notebook in Jupyterhub for your LUSID domain and then sign in to the web app to see the results on the Data Management > Instruments dashboard. Click the Configuration button (top right, highlighted in red) and then Add column to add the Country property to the default view (in green):

Creating a corporate action source and loading corporate actions

We can call the CreateCorporateActionSource API to create a corporate action source and then the UpsertInstrumentEvents API to load corporate actions into it representing cash dividends for BP and Microsoft. Each corporate action has:

• An ex-dividend date of 6 March 2023. LUSID automatically applies a corporate action to any transaction portfolio with a subscription to the source and a holding in the underlying instrument before this date.
• A payment date of 10 March 2023. LUSID automatically settles a corporate action on this date.
• An input transition of 1 unit to signify that the impact of the corporate action is on a per-share basis.
• An output transition of 0.1 in a currency instrument to signify a dividend of 10 pence per share (for BP) or 10 cents per share (for Microsoft).

Step 2 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. Once executed, you can see the loaded corporate actions on the Data Management > Corporate Actions dashboard for a suitable range of dates:

Setting up a transaction portfolio and attaching a tax-related property

We can call the:

• CreatePortfolio API to create a GBP-denominated transaction portfolio that:
  • Subscribes to our corporate action source.
  • Has a tax-related property (with a 3-stage key of Portfolio/Tax/Domicile) to help LUSID determine the correct rate of withholding tax for cash dividends, in conjunction with the similar instrument properties.
  • Registers a sub-holding key (SHK) that can be used to report withholding tax as separate cash holdings.
• AdjustHoldings API to set initial positions for BP, GBP, Microsoft and USD in the portfolio, backdated to 2 January 2023.

Step 3 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. Once executed, you can see the portfolio details on the Data Management > Corporate Actions dashboard, here with the Domicile property added to the default view:

To confirm the initial positions on 2 January 2023, navigate to Dashboard > Holdings and set the Effective dropdown appropriately:

Creating a tax rule set to calculate different rates of withholding tax

We can call the CreateTaxRuleSet API to create a tax rule set that enables LUSID to determine the correct rate of tax to apply to corporate actions matching a set of criteria on a particular date.

Note the following:

• A tax rule set has an effective (or start) date that applies until it is superseded by a tax rule set with the same scope and code and a subsequent date.
• A tax rule set can have any number of tax rules to distinguish between different rates. These are processed in order and, for each corporate action, the first matching rule applies. In our example, we'll have two rules, to distinguish between a withholding tax rate of 25% for UK equities and 10% for US equities.
• A tax rule can have any number of match criteria, each of which compares a value against a property in either the Instrument, Portfolio or InstrumentEvent (that is, corporate action) domains. Every match criteria must be met for the tax rule to apply. In our example, we'll compare against the properties attached to equity instruments and to the transaction portfolio.
• A tax rule set must have an output property that stores the calculated amount of tax due for matching corporate actions. This property must be from the Transaction domain; in our example, it has a 3-stage key of Transaction/Tax/AmountDue.

Step 4 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. Tax rule sets are not yet available in the LUSID web app, but we can call the ListTaxRuleSets API and view the definition as a Pandas dataframe:

Creating a custom transaction type to report withholding tax separately

We can call the SetTransactionType API to create a custom BreakOutWithholdingTaxAsSeparateCashHoldingType transaction type that overrides the built-in Dividend transaction type for corporate actions representing cash dividends.

Our custom transaction type has two movements:

• A positive first movement with a type of CashCommitment that uses the built-in Side1 to increase main portfolio cash balances by dividend amounts.
• A negative second movement with a type of CashCommitment that uses a custom BreakOutWithholdingTaxAsSeparateCashHoldingSide side (created using the SetSideDefinition API) to capture the tax amounts due stored in the Transaction/Tax/AmountDue output property and maps them to the portfolio's SHK, to decrease separate cash balances.

To compel LUSID to override the built-in Dividend transaction type, we must attach the TransactionConfiguration/default/InstrumentEventType system property with a special value of transitionEvent/Dividend to our custom transaction type.

For much more information on configuring transaction types to change the way LUSID reports holdings, see this article.

Step 5 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. Once executed, you can see the definition of the custom side on the System Settings > Transaction Types dashboard (navigate to the Sides tab):

You can examine the custom transaction type itself on the main System Settings > Transaction Types dashboard:

Generating a holdings report

We can now call the GetHoldings API to generate a holdings report.

Step 6 of the accompanying Jupyter Notebook demonstrates how to do this using the LUSID Python SDK. Once executed, you can see the results by navigating to Dashboard > Holdings.

If we look at the holdings report for the ex-dividend date of 6 March 2023, LUSID has applied the cash dividend corporate actions to the portfolio:

• Dividend payments of £10,000 and $10,000 have been generated for BP and Microsoft respectively (highlighted in green).
• Withholding tax amounts of -£2,500 and -$1,000 have been calculated for BP and Microsoft and classified separately using the WithholdingTax SHK (highlighted in yellow).

Note all these cash amounts are of holding type CashCommitment (not yet settled):

If we look at the holdings report for the payment date of 10 March 2023, we can see that LUSID has settled the outstanding positions:

• The dividend payments have been added to the main portfolio GBP and USD cash balances.
• The withholding tax amounts of -£2,500 and -$1,000 are now each a separate Cash Balance:

For audit purposes, we can call the BuildTransactions API for a suitable window to see the output transactions that LUSID has automatically generated under-the-hood in order to impact portfolio holdings in this way. You can see the results on Dashboard > Transactions in output transaction mode (mode switch highlighted in green below).

Note the following for this range of dates (highlighted in red):

• The Units column confirms the amount of the dividend payment in the appropriate currency.
• The AmountDue column confirms the amount of withholding tax stored by the Transaction/Tax/AmountDue tax rule set output property.
• The Type column confirms the custom BreakOutWithholdingTaxAsSeparateCashHoldingType transaction type applied to the corporate action: