Inventory Bot

What It Does

The Inventory Bot automatically tracks how many units of each item you have in stock and calculates the true cost of goods sold 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 you run a business with inventory, you face a fundamental challenge: tracking what you own versus what it actually costs you to sell. Two questions matter most:

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

The Inventory Bot bridges your Financial Books (which track money flowing in and out) with a dedicated Inventory Book (which tracks quantities). Without this bot, you'd manually track quantities in spreadsheets and struggle to calculate accurate profit. Worse, you'd have no audit trail to verify your numbers. With it, the bot maintains both automatically and ensures your profit calculations reflect the real cost of goods you sold—not guesses.

How It Works

The bot operates in three phases: you record purchases and sales in your Financial Book, the bot automatically mirrors these 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, you 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 automatically detects it's a purchase and creates a matching entry in your Inventory Book: "100 units acquired at $10 per unit cost." This becomes part of the purchase log—a record of all available inventory and its cost per unit.

Recording a Sale

You sell 30 of those 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 detects it's a sale (it has good and quantity), and records it in the Inventory Book: "30 units sold." At this point, the units are marked as sold but the cost hasn't been calculated yet—that happens in the final step.

Calculating Cost of Goods Sold

Here's where the magic happens. You open the Inventory Bot menu (More > Cost of Sales) and click Calculate. The bot now matches your recorded sales to your purchase history using FIFO (First-In, First-Out). This is the critical step that transforms raw transaction data into accurate financial reporting.

The bot:

Takes all sales marked as complete but not yet cost
Looks up the purchase history for those items
Assigns the oldest purchase costs first
Records the calculated COGS entry in your Inventory Book

For your T-shirt example:

The 30 units sold came from your original purchase @ $10 each
Cost of goods sold = 30 × $10 = $300
Your profit = $900 (revenue) − $300 (cost) = $600

Your financial statements now show the true picture. The bot maintains an audit trail (the liquidation log) showing exactly which purchases were matched to which sales, so you can always verify your numbers.

FIFO: First-In, First-Out

FIFO is how the bot decides which purchase costs apply to which sales. Imagine your warehouse shelf:

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 (oldest stock moves first) 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)
- Property: exc_code = USD (or EUR, GBP, etc.)
Inventory Book — Tracks quantities (one per collection)
- Property: inventory_book = true

Account Groups

Any group containing inventory you want to track must have:

Property: exc_code = the same currency as the Financial Book

The bot uses this to match items to the right 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 unit

Optional: order (if multiple purchases the same day: 1st, 2nd, etc.)

Sale

Records items going out. Required properties:

good — The account name of the item being sold
quantity — How many units

Optional: sale_invoice, order

Additional Costs

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

purchase_code — MUST match the original purchase to link them
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 (if partial return)

The bot reduces the original purchase cost accordingly.

Key Rules

Always check ✅ transactions after recording them. This is how the bot knows to process them and sync to the Inventory Book. This is an important mechanism so you can verify your purchases and sales, before they are included into your Inventory.

Only edit the Financial Book. (DON'T edit the Inventory Book) The Inventory Book is managed entirely by the bot—it maintains the audit trail. If you manually edit Inventory Book transactions or properties, you'll break the calculations and lose your audit trail. Similarly, don't manually edit COGS calculation results; always use Reset and recalculate if needed.

The good property on sales must match your account name exactly. If you created an account called "Coffee Bags," the property value must be "Coffee Bags" (case-sensitive). This is how the bot links sales back to the correct purchase history.

Include all required properties on every transaction. The bot uses these properties (purchase_code, purchase_invoice, quantity, good, sale_invoice) to determine transaction type and route it correctly.

Real Example: Coffee Roastery

You roast and sell coffee. Here's what happens:

January:

Buy 100 bags @ $5 each = $500 (purchase_code: COFFEE-001)
Sell 60 bags for $900

When you calculate COGS:

60 bags × $5 = $300 cost
Profit: $900 − $300 = $600
Inventory remaining: 40 bags @ $5 = $200 value

February:

Buy 80 bags @ $6 each = $480 (purchase_code: COFFEE-002)
Sell 100 bags for $1,500

When you calculate COGS (FIFO):

First 40 bags from January @ $5 = $200
Next 60 bags from February @ $6 = $360
Total COGS: $560
Profit: $1,500 − $560 = $940
Inventory remaining: 20 bags @ $6 = $120 value

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
All inventory accounts

The bot processes all unchecked transactions, applies FIFO, and checks them when done.

To Reset: If you need to recalculate (perhaps you added a transaction with an earlier date), click Reset to clear previous calculations for that account, then Calculate again.

Common Issues

"Inventory Book has pending tasks" — The Inventory Book has uncompleted transactions. Wait or refresh the page.

"Sale quantity exceeds available inventory" — You recorded a sale with more units than you've purchased. Check your purchase quantities.

"Account flagged for rebuild" — You recorded a sale with a date earlier than your last COGS calculation. The bot will recalculate from scratch on next calculation to ensure accuracy.

"Financial Book not found" — The item's group exc_code doesn't match any Financial Book in the collection. Verify both have the same currency code.

What You Get

✓ Automatic inventory tracking — No manual spreadsheet updates. Just record the transaction and check it.
✓ Accurate COGS — Based on actual purchase costs matched to sales, not guesses or averages.
✓ Audit trail — Every COGS calculation shows exactly which purchases were matched to which sales, so your numbers are always verifiable.
✓ True profit — Revenue − Cost of Goods Sold = profit that reflects reality.
✓ Real-time inventory visibility — Know exactly how many units you have and what they're worth at cost.
✓ Tax compliance — FIFO is accepted by tax authorities worldwide and creates the documentation you need for audits.
✓ One source of truth — Your Financial Book and Inventory Book stay in sync automatically, eliminating reconciliation headaches.