Manage Stock Book in sync with Financial Books upon buying and seling inventory instruments.
It works by monitoring Financial Books and tracking quantities of instruments bought or sold in a separate Stock Book.
The process of tracking realized gains and losses upon sales follows the FIFO (First-In, First-Out) method.
Financial and Instruments Books must be in the same Collection.
Only a single Instruments Book should be defined per Collection.
The Instruments Book is identified by a single book in the Collection with the decimal places set to 0 (zero) or by the stock_book
property set to true
.
The Stock Bot interacts with the following properties:
exc_code
: Required - The book exchange code to match the stock_exc_code
.stock_historical
: Optional - true/false - Defines if realized results calculations should consider historical costs and rates. If set to false or not present, the last Forward valuation will be used instead. See Forward Date Service.stock_book
: Optional - true/false - Identifies the Instruments book of the collection. If not present, decimal places must be set to 0 (zero) in the book settings.stock_exc_code
: Required - Defines the exchange code of the instrument that will have quantities mirrored into the Stock Book. Only transactions with accounts within groups with stock_exc_code
set will be mirrored.stock_fees_account
: Optional - The fees account used by the broker account. The broker account is identified by having an associated fees account.quantity
: Required - The quantity of the instruments to track.When calculating realized results, the market value of remaining instruments can be automatically adjusted on Financial Books to match the last realized price of that instrument. This valuation procedure is known as Mark-To-Market.
The Stock Bot adds the following properties to the generated transactions in the Instruments Book:
purchase_amount/fwd_purchase_amount
: The financial amount the instrument was bought.purchase_price/fwd_purchase_price
: The price the instrument was bought.purchase_exc_rate/fwd_purchase_exc_rate
: The exchange rate (local currency to base currency) when the instrument was bought.sale_amount/fwd_sale_amount
: The financial amount the instrument was sold.sale_price/fwd_sale_price
: The price the instrument was sold.sale_exc_rate/fwd_sale_exc_rate
: The exchange rate (local currency to base currency) when the instrument was sold.sale_date
: The date when the instrument was sold.order
: Index used to reorder transactions that happened on the same day.original_quantity
: The original quantity of the instrument (used to rebuild FIFO gains/losses if needed).Observation:
The properties starting with fwd
above have the same meaning as their peers, however, their values may differ if a Forward Date was set to that instrument. In that case, there are also other fwd
properties, which are references that connect forwarded transactions to their logs.
In order to close a period and set a closing date to the Stock Book, instruments must be carried to the next period. The proper way to do so is by setting a Forward Date to the accounts in the Instruments Book.
Each unchecked transaction will have its date, price and exchange rate updated to the current valuation, leaving a log of its previous state behind. When the last instrument is successfully forwarded a closing date will be set on the Stock Book one day before the Forward Date.
Once an instrument is forwarded, future FIFO calculations will consider the new Forward valuation. In order to keep calculating gains/losses over the historical basis, the property stock_historical
must be set to true
on the Instruments Book.
When forwarding instruments, the Stock Bot also adds the following properties to the forwarded transactions:
date
: The date when the transaction has occurred.hist_order
: The historical index the transaction had before being forwarded.hist_quantity
: The historical quantity of the instrument (used to rebuild FIFO gains/losses if needed).fwd_log
: The id of the forwarded transaction previous state (a copy of the transaction before being forwarded).