--- title: "Modelling equities in LUSID" slug: "modelling-equities-in-lusid" tags: ["instrument", "equity", "simple instrument"] updated: 2025-04-15T15:12:53Z published: 2025-04-15T15:12:53Z canonical: "support.lusid.com/modelling-equities-in-lusid" --- > ## 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. # Modelling equities in LUSID You can model an equity as an instrument of type `Equity` in LUSID. [See all supported instruments](/v1/docs/what-instruments-does-lusid-support). ## Mastering an instrument There are [numerous tools](/v1/docs/how-do-i-master-an-instrument) you can use to master an `Equity` in the LUSID Security Master. Some fields are common to all types of instrument, such as an intuitive `name`, the [requirement to specify a set](/v1/docs/understanding-instrument-identifiers) of `identifiers`, and the facility to [store extra information](/v1/docs/properties) as `properties`. Fields in the economic `definition` object are specific to `Equity`. For more information on these fields, select **Equity** from the **definition** dropdown in the [UpsertInstruments](https://www.lusid.com/docs/api/lusid/endpoints/instruments/UpsertInstruments) API reference: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(732).png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A17Z&se=2026-11-09T07%3A00%3A17Z&sr=c&sp=r&sig=M2%2Bv39%2BLOsRlhh%2BOyVuOT8jwQ25vRshXYoIOiy6vcJM%3D) In this tutorial we’ll master [BP PLC $0.25 shares traded in London](https://www.londonstockexchange.com/stock/BP./bp-plc/company-page) by calling the `UpsertInstruments` API as follows: ```json curl -X POST 'https://.lusid.com/api/api/instruments?scope=MyCustomInstrScope'   -H 'Content-Type: application/json-patch+json'   -H 'Authorization: Bearer '   -d '{  "upsert-request-1": {    "name": "BP $0.25 LDN",    "identifiers": {      "ClientInternal": {"value": "bp-plc-ldn"},      "Figi": {"value": "BBG000C05BD1"},      "Isin": {"value": "GB0007980591"},      "Sedol": {"value": "0798059"}    },    "definition": {      "instrumentType": "Equity",      "domCcy": "GBP"    }  } }' ``` Note the following: - We’ve chosen to master this instrument in a [custom instrument scope](/v1/docs/understanding-instrument-scopes) (specified as a query parameter in the URL). - The `identifiers` object identifies the instrument using a mixture of [unique and non-unique identifiers](/v1/docs/what-are-unique-and-non-unique-identifiers). - In the economic `definition` object: - The `instrumentType` must be `Equity`. - The `domCcy` must be an [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217), for example `GBP`. Providing the request is successful, the response: - Confirms the globally-unique [LUID](/v1/docs/what-is-a-lusid-instrument-id-or-luid) for the instrument. - Generates extra fields that are stored as part of the instrument definition and can be [filtered on](/v1/docs/filtering-information-retrieved-from-lusid). - Supplies default values for fields not explicitly specified in the request: ```json {  "values": {    "upsert-request-1": {      "scope": "MyCustomInstrScope",      "lusidInstrumentId": "LUID_00003EDQ",      "version": {        "asAtCreated": "2025-04-15T12:12:35.6248820+00:00",        "userIdCreated": "00u91lo2d7X42sdse2p7",        "requestIdCreated": "2025041512-b098190a3157476d9b522604be3e9589",        "asAtModified": "2025-04-15T12:12:35.6248820+00:00",        "userIdModified": "00u91lo2d7X42sdse2p7",        "requestIdModified": "2025041512-b098190a3157476d9b522604be3e9589",        "asAtVersionNumber": 1,        "entityUniqueId": "b6000edd-06e1-4842-bba3-8735cacc348c"      },      "name": "BP $0.25 LDN",      "identifiers": {        "LusidInstrumentId": "LUID_00003EDR",        "ClientInternal": "bp-plc-ldn",        "Sedol": "0798059",        "Isin": "GB0007980591",        "Figi": "BBG000C05BD1"      },      "properties": [],      "instrumentDefinition": {        "identifiers": {},        "domCcy": "GBP",        "lotSize": 1,        "instrumentType": "Equity"      },      "state": "Active",      "assetClass": "Equities",      "domCcy": "GBP",      "relationships": []    }  },  "staged": {},  "failed": {},  ... } ``` ## Booking a transaction to establish a position Once an instrument is mastered, we can [book a transaction](/v1/docs/how-do-i-create-or-update-a-transaction) to record the acquisition of a quantity in a suitable portfolio, for example by calling the `BatchUpsertTransactions` API as follows: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/UK/transactions/$batchUpsert?successMode=Partial&preserveProperties=true'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "transactionRequest-1": {    "transactionId": "equity_purchase_001",    "type": "BuyEquity",    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003EDR"},    "transactionDate": "2025-04-02T00:00:00.0000000+00:00",    "settlementDate": "2024-04-05T00:00:00.0000000+00:00",    "units": 10000,    "transactionPrice": {      "price": 3.50,      "type": "Price"    },    "totalConsideration": {      "currency": "GBP",      "amount": 0    },    "properties": {      "Transaction/MyProperties/TotalCapitalisedFees": {        "key": "Transaction/MyProperties/TotalCapitalisedFees",        "value": {          "metricValue": {            "value": 1330,            "unit": "GBP"          }        }      }    }  } }' ``` Note the following: - The `instrumentIdentifiers` field uses the LUID to [resolve the transaction](/v1/docs/how-does-lusid-resolve-data-to-instruments) to the correct instrument, but it could use any unique identifier. - The `type` field invokes a `BuyEquity` [transaction type](/v1/docs/what-is-a-transaction-type) to confer a particular economic impact on the transaction (see below). - The `units` field specifies the purchase amount. - The `transactionPrice` object records the market price (in pounds not pence). This is used by LUSID to automatically calculate gross consideration (see below). - The `totalConsideration` object: - Sets the settlement currency to `GBP`. - Specifies a settlement cost of `0` to enable LUSID to automatically derive total consideration (see below). - The trade commission is recorded using a [custom property](/v1/docs/properties). > **Note**: This example assumes the transaction, settlement and portfolio currencies are all the same. If not, you can [specify exchange rates](/v1/docs/transactions-and-exchange-rates). We can call the [SetTransactionType](https://www.lusid.com/docs/api#operation/SetTransactionType) API to create a `BuyEquity` transaction type as follows: ```json curl -X PUT 'https://.lusid.com/api/api/transactionconfiguration/types/default/BuyEquity?scope=default'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "aliases": [    {      "type": "BuyEquity",      "description": "Transaction type for equity purchases",      "transactionClass": "Basic",      "transactionRoles": "Longer",      "isDefault": false    }  ],  "movements": [    {      "name": "Increase units of security",      "movementTypes": "StockMovement",      "side": "Side1",      "direction": 1    },    {      "name": "Decrease cash balance by total consideration",      "movementTypes": "CashCommitment",      "side": "Side2",      "direction": -1    }  ],  "calculations": [    {      "type": "Txn:GrossConsideration"    },    {      "type": "DeriveTotalConsideration",      "formula": "Txn:GrossConsideration + Properties[Transaction/MyProperties/TotalCapitalisedFees]"    }  ] }' ``` Note the following: - The `Txn:GrossConsideration` [calculation](/v1/docs/what-is-a-transaction-type-calculation#txngrossconsideration) automatically calculates gross consideration according to the formula `price * units`, and stores the result in the `Transaction/default/GrossConsideration` system property. - The `DeriveTotalConsideration` [calculation](/v1/docs/what-is-a-transaction-type-calculation#derivetotalconsideration) automatically calculates total consideration according to the given, user-defined formula, which in this case sums gross consideration and total fees; this is stored as the `totalConsideration.amount` of the transaction. - The `StockMovement` uses the [built-in](https://support.lusid.com/docs/what-built-in-transaction-types-and-sides-are-provided-with-lusid#builtin-sides) `Side1` side to update a holding in the instrument with the specified number of units at a cost of the total consideration. [See how LUSID calculates holding cost](/v1/docs/how-is-cost-calculated-in-lusid). - The `CashCommitment` movement uses the built-in `Side2` to decrease the instrument currency holding by the total consideration. ### Confirming positions You can [generate a holdings report](/v1/docs/how-do-i-generate-a-holdings-report) to see the impact of the transaction on security and cash holdings, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(734).png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A17Z&se=2026-11-09T07%3A00%3A17Z&sr=c&sp=r&sig=M2%2Bv39%2BLOsRlhh%2BOyVuOT8jwQ25vRshXYoIOiy6vcJM%3D) ### Auditing LUSID’s transaction type calculations You can examine the [output transaction](/v1/docs/input-and-output-transactions) automatically generated by LUSID to audit calculated amounts, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(735).png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A17Z&se=2026-11-09T07%3A00%3A17Z&sr=c&sp=r&sig=M2%2Bv39%2BLOsRlhh%2BOyVuOT8jwQ25vRshXYoIOiy6vcJM%3D) ## Valuing your position To value your position, work through our [valuation checklist](/v1/docs/valuation-checklist). Note the only pricing model available to an `Equity` is `SimpleStatic`, which calculates PV as `holding units * market price`. ## Monitoring the lifecycle of the instrument An `Equity` does not have an expiry or maturity date, so the instrument does not have a lifecycle in the normal sense. Typically, you close your position at a time when P&L is favourable to you, though real-world change of control events such as mergers or insolvencies may impact the outcome. You can load a stream of corporate actions into a source and [trigger LUSID to emit events](/v1/docs/understanding-dedicated-corporate-action-events) that you can then handle appropriately. LUSID does have tools that enable you to monitor portfolio cashflows that derive from a dividend payment or some other corporate action. You can: - Use the **Cash Ladder** dashboard in the [LUSID web app](https://www.lusid.com/app/home). - Call the LUSID [GetPortfolioCashLadder](https://www.lusid.com/docs/api#operation/GetPortfolioCashLadder) API directly. - [Schedule a job](/v1/docs/scheduler) to create a regular report.