Confused about transaction/split

[John Ralls]

Niranjan,

The transaction carries the date, description, and the CURRENCY that the transaction will be balanced in. In theory that doesn’t have to be either the currency in which the stock is priced nor the currency of the account from which you transfer the payment, but the more currencies that are involved the harder it is for GnuCash’s balancing code to get it right, so everything works best if there’s only one currency.

Before you create the transaction you must already have created the stock’s commodity and an account of type STOCK or MUTUAL FUND denominated in that commodity. That account should be parented with an account of either type ASSET or type BANK denominated in the currency in which the stock trades. In GnuCash debits are positive numbers and credits are negative numbers. You’ll create a split in that account with the number of shares as the amount and the value as the extended value (i.e. amount * price) in the transaction currency. You’ll create a second split in the cash account with the amount set to the negative equivalent in the cash account’s currency and value as the negative extended value in the transaction currency.

So the simplest example is all currencies are, say, INR. 
Transaction.Date = 2026-05-31, Transaction.Description = “Buy XYZ 100 @ 25.00 INR/share”, Transaction.Currency = INR
Split1.Account = /Assets/Investment/Broker/Stocks/XYZ, Split1.Amount = 100, Split1.Value = 2500.00
Split2.Account = /Assets/nvestment/Broker/Cash, Split2.Amount = -2500.00, Split2.Value = -2500.00.

A more complicated example where the stock and cash account are still in INR but the transaction currency is USD. Today’s exchange rate is .010 USD = 1 INR so it will look like

Transaction.Date = 2026-05-31, Transaction.Description = “Buy XYZ 100 @ 25.00 INR/share”, Transaction.Currency = USD
Split1.Account = /Assets/Investment/Broker/Stocks/XYZ, Split1.Amount = 100, Split1.Value = 25.00
Split2.Account = /Assets/nvestment/Broker/Cash, Split2.Amount = -2500.00, Split2.Value = -25.00.

Regards,
John Ralls

> On May 24, 2026, at 12:23, Niranjan Rao <nhrdls at gmail.com> wrote:
> 
> Greetings,
> 
> I am trying to add a shares purchase transaction. I've account for given stock/commodity and a cash account from which money will be transferred
> 
> As I understand one part of the split should come from cash which will be currency or dollar value. Other split will be number of shares purchased for that money. 
> 
> I am trying to use API (through my Java library) to create a transaction and not able to get it right. I am especially getting confused about the value and amount parts. I am not sure which field will represent the quantity or number of shares purchased.
> 
> Here is the general flow I am calling from Java 
> 
> 
> 
> Create transaction - xaccMallocTransaction
> 
> Set currency as my commodity of stock - xaccTransSetCurrency
> 
> Create split xaccTransSetCurrency
> 
> 
> 
> Set appropriate account and parent xaccSplitSetAccount, xaccSplitSetParent
> 
> 
> 
> I now have three data fields available - total amount in dollar  (moneySpent), number of shares purchased (quantity) and price  (price) at which they were purchased. I tried various combinations of xaccSplitSetAmount, xaccSplitSetValue, xaccSplitSetSharePriceAndAmount
> 
> 
> 
> But not matter what I do, I always get imbalance record or price gets calculated wrong. In general split entry is wrong. Mirroring split from cash account looks correct. At least that account shows the entry the way it should be.
> 
> Can you please help me with the right method calls and parameters I need to pass get the transaction right. I've intentionally used slightly different variable names in the email so as to avoid the confusion with the actual parameter names used in header files.
> 
> 
> 
> Regards,
> 
> Niranjan
> 
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20260524/74341151/attachment.htm>