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. See Rebuilding inventory below for how to fix it.
• “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

Rebuilding inventory

When an inventory account is marked for rebuild, it means you recorded a transaction with a date earlier than your last COGS calculation. The bot flags it to prevent incorrect profit calculations.

The problem this solves

FIFO cost matching depends on perfect chronological order. Adding a transaction out of sequence breaks the FIFO logic:

• January 31: You calculate COGS (the bot locks in this date)
• February 15: You discover a sale from January 15 that you missed
• Problem: The January 15 sale should have been matched to January purchases, but COGS was already calculated with February purchases in the mix
• Result: Your profit calculation is wrong — the wrong purchases were matched to the wrong sales

The rebuild flag catches this so you can fix it.

Key causes for the rebuild flag

Backdated transactions — you recorded a transaction with a date before the last COGS calculation date.

When it happens	Example
After calculating COGS	You calculate on Feb 28
Then add an earlier transaction	You record a Jan 15 sale you forgot
The bot flags the account	Marked for rebuild

Manual edits to the Inventory Book — someone manually edited a transaction in the Inventory Book after the bot created it.

What you did	Why it’s dangerous
Changed a quantity in the Inventory Book	Breaks the link to your Financial Book
Modified a property or date	Invalidates the FIFO matching
Deleted a transaction	Audit trail is incomplete

Caution

Only edit the Financial Book. The Inventory Book is managed by the bot and maintains your audit trail.

What to do

1. Understand why it was flagged — check if you added a backdated transaction or manually edited the Inventory Book.
2. Verify the transaction is correct — confirm the transaction date is accurate and all properties (quantity, good, purchase_code, etc.) are correct. If not, fix it in the Financial Book and re-check it.
3. Recalculate — click Reset (clears previous COGS calculations), then click Calculate Cost of Sales (recalculates with the correct order). The rebuild flag clears automatically.

Caution

Never ignore this warning. FIFO accuracy is essential for correct profit reporting and tax compliance.