--- title: "Assigning transactions to custodian accounts" slug: "assigning-transactions-to-custodian-accounts" updated: 2026-08-16T09:23:11Z published: 2026-08-16T09:23:11Z canonical: "support.lusid.com/assigning-transactions-to-custodian-accounts" --- > ## 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. # Assigning transactions to custodian accounts Consider the example of equity purchase transactions booked into a portfolio with a `BuyEquity` transaction type that has two movements: 1. A `StockMovement` that increases the units/cost of a holding in the equity. 2. A `CashCommitment` that decreases the units/cost of a holding in the instrument currency. Let’s assume we have [created and registered](/v1/docs/how-do-i-create-and-register-custodian-accounts) the following four custodian accounts with the portfolio: | Custodian account | Intended purpose | Account type | Default for account type? | Related accounts | | --- | --- | --- | --- | --- | | `HSBC-Stock` | Movements in UK stocks | `Stock` | ✅ | `HSBC-Cash` | | `HSBC-Cash` | Movements in GBP | `Cash` | ✅ | | | `JPM-Stock` | Movements in US stocks | `Stock` | ❌ | `JPM-Cash` | | `JPM-Cash` | Movements in USD | `Cash` | ❌ | | ## Making transaction types custodian-aware To assign movements to custodian accounts, set the `custodianAccountType` field to an appropriate account type. For example, the following call to the [SetTransactionType](https://www.lusid.com/docs/api/lusid/endpoints/transaction-configuration/SetTransactionType/) API for `BuyEquity` sets: - The `StockMovement` to `Stock` so LUSID (can only) resolve stock movements to custodian accounts with a matching account type of `Stock` - The `CashCommitment` to `Cash` so LUSID (can only) resolve cash movements to custodian accounts with a matching account type of `Cash` ```json {  "aliases": [    {      "type": "BuyEquity",      "description": "Equity purchases",      "transactionClass": "Trading",      "transactionRoles": "LongLonger",      "isDefault": false    }  ],  "movements": [    {      "movementTypes": "StockMovement",      "side": "Side1",      "direction": 1,      "custodianAccountType": "Stock"    },    {      "movementTypes": "CashCommitment",      "side": "Side2",      "direction": -1,      "custodianAccountType": "Cash"    }  ] } ``` ## Nominating all custodian accounts explicitly When booking equity purchase transactions using `BuyEquity` we have the option to specify a set of `custodianEntries` explicitly nominating custodian accounts for stock and cash movements. For example, the following request to the [BatchUpsertTransactions](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/BatchUpsertTransactions/) API: - Nominates the `JPM-Stock` custodian account for stock movements, since its `accountType` of `Stock` matches the `custodianAccountType` of `Stock` on the `StockMovement` - Nominates the `JPM-Cash` custodian account for cash movements , since its `accountType` of `Cash` matches the `custodianAccountType` of `Cash` on the `CashCommitment` ```json {  "transactionRequest-1": {    "transactionId": "Txn-001",    "type": "BuyEquity",    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C6K6G9"},    "transactionDate": "2026-01-01T00:00:00.0000000+00:00",    "settlementDate": "2026-01-03T00:00:00.0000000+00:00",    "units": 200,    "transactionPrice": {"price": 3, "type": "Price"},    "totalConsideration": {"amount": 600, "currency": "GBP"},    "custodianEntries": [      {        "accountId": {          "scope": "CustAccsV2",          "code": "JPM-Stock"        }      },      {        "accountId": {          "scope": "CustAccsV2",          "code": "JPM-Cash"        }      }    ]  } } ``` We can examine holdings and group by the custodian account SHK to see the resulting stock and cash holdings successfully segregated by custodian account: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-7DVGJZHI.png) LUSID provides a [resolution reason](/v1/docs/how-does-lusid-resolve-transactions-to-custodian-accounts#understanding-resolution-types) for each movement on the output transaction: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-SSUCFWE8.png) ## Nominating a custodian account just for stock movements As an alternative, we could nominate just `JPM-Stock` as the custodian account for stock movements using `BuyEquity` but omit an explicit nomination for cash movements, for example: ```json {  "transactionRequest-1": {    "transactionId": "Txn-001",    "type": "BuyEquity",    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C6K6G9"},    "transactionDate": "2026-01-01T00:00:00.0000000+00:00",    "settlementDate": "2026-01-03T00:00:00.0000000+00:00",    "units": 200,    "transactionPrice": {"price": 3, "type": "Price"},    "totalConsideration": {"amount": 600, "currency": "GBP"},    "custodianEntries": [      {        "accountId": {          "scope": "CustAccsV2",          "code": "JPM-Stock"        }      }    ]  } } ``` This time, LUSID resolves cash to the default custodian account for the `Cash` account type, which in our example is `HSBC-Cash`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-H7PAOQX1.png) The resolution reason for the cash movement is now different: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-0JDYKJRC.png) ## Omitting nominated custodian accounts entirely If we omit `custodianEntries` entirely from the request then LUSID falls back to the default custodian accounts for the `Stock` and `Cash` account types, which in our example is `HSBC-Stock` and `HSBC-Cash` respectively: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-GI9GLKTJ.png) The resolution reason for both movements is different again: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-QAV348L0.png) > **Note**: If there were no default custodian accounts for the `Stock` and `Cash` account types then all `BuyEquity` movements would fail to resolve and stock and cash holdings would not be segregated by custodian account. ## Handling auto-generated instrument event transactions LUSID can automatically generate transactions in response to instrument lifecycle or corporate action events impacting certain instruments. For example, we might load a `CashDividendEvent` of 20 pence per share for our UK equity into a corporate action source. On the ex-date, LUSID automatically generates a transaction for a dividend amount of 200 units held * £0.20 = £40 and adds it to a GBP cash holding. By default, auto-generated transactions inherit SHKs and custodian account information from the original holding. While our equity is assigned to the `JPM-Stock` custodian account, income should typically be directed to a `Cash`-type custodian account such as `JPM-Cash`. To do this, we can [create or update](/v1/docs/how-do-i-create-and-register-custodian-accounts) the `JPM-Stock` custodian account to set the `CustodianAccount/default/RelatedAccounts` system property to a related cash account, for example: ```json [  {    "scope": "CustAccsV2",    "code": "JPM-Stock",    "accountType": "Stock"    "properties": {      "CustodianAccount/default/RelatedAccounts": {        "key": "CustodianAccount/default/RelatedAccounts",        "value": {          "labelValueSet": {            "values": ["CustAccsV2/JPM-Cash"]          }        }      }    },    ...  } ] ``` Then, we can make the [DividendIncome](/v1/docs/recommended-transaction-types-for-corporate-action-events#cashdividendevent) transaction type processing `CashDividendEvent` custodian-aware, for example: ```json {  "aliases": [    {      "type": "DividendIncome",      "description": "Transaction type for cash dividend event",      "transactionClass": "Dividend",      "transactionRoles": "Longer",      "isDefault": false    }  ],  "movements": [    {      "movementTypes": "CashAccrual",      "side": "Side1",      "direction": 1,      "custodianAccountType": "Cash"    },    ...  ] }' ``` Now, LUSID resolves the cash movement to the related `JPM-Cash` custodian account instead of `JPM-Stock`, reducing the total negative balance: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-FZUTLWGM.png) The resolution reason is available on the output transaction: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-DAATGKP9.png)