Inventory Bot

The Inventory Bot automatically tracks how many units of each item you have in stock and calculates the true cost of goods sold (COGS) when you make a sale. It bridges your Financial Books (which track money) with a dedicated Inventory Book (which tracks quantities), ensuring your profit calculations account for what items actually cost.

Why this matters

When running a business with inventory, two questions matter most:

• How many units do I have right now?
• When I sold those units, what did they cost me?

Without the Inventory Bot, you would manually track quantities in spreadsheets and struggle to calculate accurate profit. With it, the bot maintains both automatically and ensures your profit calculations reflect the real cost of goods sold.

How it works

The bot operates in three phases: you record purchases and sales in your Financial Book, the bot mirrors them in the Inventory Book with quantities, and finally you run a calculation that matches purchases to sales using FIFO.

Recording a purchase

You buy 100 units of T-shirts for $1,000. In your Financial Book, record:

Date	Amount	From Account	To Account	Description	Properties
01/15/2025	$1,000	Bank	T-shirts	Purchase order	purchase_invoice: INV-001 purchase_code: TSHIRT-001 quantity: 100

When you check this transaction, the bot detects it as a purchase and creates a matching entry in your Inventory Book: “100 units acquired at $10 per unit cost.”

Recording a sale

You sell 30 T-shirts for $900. In your Financial Book:

Date	Amount	From Account	To Account	Description	Properties
02/01/2025	$900	Sales Revenue	Bank	Sale	sale_invoice: SALE-001 good: T-shirts quantity: 30

When you check this transaction, the bot records it in the Inventory Book: “30 units sold.” The cost hasn’t been calculated yet — that happens in the next step.

Calculating cost of goods sold

Open the Inventory Bot menu (More > Cost of Sales) and click Calculate. The bot matches recorded sales to purchase history using FIFO (First-In, First-Out):

• The 30 units sold came from the original purchase at $10 each
• Cost of goods sold = 30 x $10 = $300
• Profit = $900 (revenue) - $300 (cost) = $600

The bot maintains a liquidation log showing exactly which purchases were matched to which sales — a complete audit trail.

FIFO: First-In, First-Out

FIFO determines which purchase costs apply to which sales. The oldest stock moves first:

Oldest purchase → [100 units @ $10 each]
                  [50 units @ $12 each]
Newest purchase → [20 units @ $15 each]

When you sell 120 units, the bot takes from the oldest first:

• 100 units @ $10 = $1,000
• 20 units @ $12 = $240
• Total COGS = $1,240

FIFO reflects how real warehouses work and is accepted by tax authorities worldwide.

Setup requirements

Collection structure

Your Financial Books and Inventory Book must belong to the same collection:

Financial Book — records money flowing in and out (one per currency):

exc_code: USD

Inventory Book — tracks quantities (one per collection):

inventory_book: true

Account groups

Any group containing inventory items must have:

exc_code: USD

The bot uses this to match items to the correct currency’s financial data.

Transaction types

Purchase

Records items coming in. Required properties:

• purchase_invoice — reference number
• purchase_code — links to related additional costs or credit notes
• quantity — how many units

Optional: order (sequence when multiple purchases happen on the same day)

Sale

Records items going out. Required properties:

• good — the account name of the item being sold (must match exactly, case-sensitive)
• quantity — how many units

Optional: sale_invoice, order

Additional costs

Records extra costs added to a purchase (shipping, import duties). Required:

• purchase_code — must match the original purchase
• purchase_invoice — reference for the cost invoice

The bot adds this to the original purchase cost, raising the per-unit cost for COGS calculations.

Credit note

Records a refund or discount on a purchase. Required:

• purchase_code — must match the original purchase
• credit_note — invoice number of the credit

Optional: quantity (for partial returns)

Key rules

Caution

Always check transactions after recording them. This is how the bot knows to process them and sync to the Inventory Book — it gives you a chance to verify purchases and sales before they enter your inventory.

Caution

Only edit the Financial Book. The Inventory Book is managed entirely by the bot and maintains the audit trail. Manually editing Inventory Book transactions or properties will break calculations.

• The good property on sales must match your account name exactly (case-sensitive).
• Include all required properties on every transaction.
• The bot automatically protects FIFO accuracy across periods — backdated transactions trigger a rebuild flag.

Real example: Coffee Roastery

January:

• Buy 100 bags @ $5 each = $500 (purchase_code: COFFEE-001)
• Sell 60 bags for $900
• COGS: 60 bags x $5 = $300 | Profit: $600
• Remaining inventory: 40 bags @ $5

February:

• Buy 80 bags @ $6 each = $480 (purchase_code: COFFEE-002)
• Sell 100 bags for $1,500
• COGS (FIFO): 40 bags from January @ $5 = $200, then 60 bags from February @ $6 = $360
• Total COGS: $560 | Profit: $940
• Remaining inventory: 20 bags @ $6

Calculating and resetting

To calculate COGS: Open the Inventory Bot menu and select Calculate Cost of Sales. You can calculate for a single account, all accounts in a group, or all inventory accounts.

To reset: If you need to recalculate (perhaps you added a backdated transaction), click Reset to clear previous calculations, then Calculate again.

Forward date and period closure

The Inventory Bot uses an automatic forward date mechanism that activates when you calculate COGS. The calculation date is stored on each inventory account and acts as a period boundary.

• Transactions after this date — processed normally in the next calculation
• Transactions before this date — trigger a rebuild flag to protect FIFO accuracy

This prevents accidentally inserting past-period transactions without the bot detecting the inconsistency.

Tip

The automatic forward mechanism prevents a common mistake: manually forwarding while leaving uncalculated transactions. By tying it to the calculation, the bot ensures period boundaries always align with actual COGS calculations.

Common issues

• “Inventory Book has pending tasks” — wait or refresh; the Inventory Book has uncompleted transactions.
• “Sale quantity exceeds available inventory” — you recorded a sale with more units than purchased. Check your purchase quantities.
• “Account flagged for rebuild” — you recorded a transaction dated before your last COGS calculation. The bot will recalculate from scratch on the next calculation. See Rebuild Inventory for details.
• “Financial Book not found” — the item’s group exc_code doesn’t match any Financial Book in the collection.

What you get

• Automatic inventory tracking — just record and check transactions
• Accurate COGS — based on actual purchase costs matched to sales via FIFO
• Audit trail — every COGS calculation shows which purchases matched which sales
• True profit — revenue minus actual cost of goods sold
• Real-time inventory visibility — unit counts and cost-basis values always current
• Tax compliance — FIFO is accepted worldwide and produces the documentation needed for audits
• One source of truth — Financial Book and Inventory Book stay in sync automatically