""" Plain-language definitions of every figure the dashboard shows — served to the UI as the content of the (i) info buttons. These live in the backend, next to the engine, ON PURPOSE: each entry describes what `journal._contribute_components`, `movement.compute_movement`, `receivable.py` and `settlements.py` actually do, and anyone changing that code is looking at the file that documents it. If you change a rule, change its definition in the same commit. Shape per entry: formula : the arithmetic, in one line source : which source-report columns / transaction types feed it note : anything Finance should know when tying it out (optional) Column names in `source` are the Amazon report's own headers (localized headers map to these via column_map.py). """ from __future__ import annotations REFUND_TYPES_LABEL = "Refund, Refund_Retrocharge, Chargeback Refund, A-to-z Guarantee Claim" DEFINITIONS: dict[str, dict[str, str]] = { # ------------------------------------------------- revenue components (journal.py) "product_sales": { "formula": "Σ `product sales`", "source": f"the `product sales` column of every row except Transfers and " f"refund-type rows ({REFUND_TYPES_LABEL})", "note": "Refund-type rows' product sales are shown in the Refunds line instead, " "so sales and refunds are visible separately.", }, "shipping_credits": { "formula": "Σ `shipping credits`", "source": "the `shipping credits` column of non-refund, non-transfer rows", }, "gift_wrap_credits": { "formula": "Σ `gift wrap credits`", "source": "the `gift wrap credits` column of non-refund, non-transfer rows", }, "other_sales_credits": { "formula": "Σ `regulatory fee`", "source": "the `regulatory fee` column of every non-transfer row", }, "refunds": { "formula": "Σ (`product sales` + `shipping credits` + `gift wrap credits`) over refund rows", "source": f"rows whose type is one of: {REFUND_TYPES_LABEL}", "note": "Negative: money returned to buyers.", }, "promotional_rebates": { "formula": "Σ `promotional rebates`", "source": "the `promotional rebates` column of every non-transfer row", }, "tax_net": { "formula": "Σ (`product sales tax` + `shipping credits tax` + `gift wrap credits tax` " "+ `tax on regulatory fee` + `promotional rebates tax` " "+ `marketplace withheld tax` + `sales tax collected`)", "source": "every tax column, netted together", "note": "Where Amazon collects and remits the tax itself, collected and withheld " "cancel and this nets to ~0.", }, "selling_fees": { "formula": "Σ `selling fees`", "source": "the `selling fees` column (referral commissions, variable closing fees)", }, "fba_fees": { "formula": "Σ `fba fees`", "source": "the `fba fees` / `fulfilment by amazon fees` column (pick & pack, weight handling)", }, "storage_fees": { "formula": "Σ `other` over FBA Inventory Fee rows", "source": "rows whose type is `FBA Inventory Fee` (monthly + long-term storage); " "the amount sits in the `other` column", }, "advertising": { "formula": "Σ (`other` + `other transaction fees`) over advertising rows", "source": "rows whose DESCRIPTION reads as advertising — \"Cost of advertising\", " "\"Sponsored Products\", Werbekosten, publicité, pubblicità, … — regardless " "of type (Amazon books these as plain `Service Fee`)", "note": "The amount column differs by marketplace: `other` in the North-America " "report, `other transaction fees` in the UK/EU report. Both are captured.", }, "other_transaction_fees": { "formula": "Σ `other transaction fees` (excluding advertising rows)", "source": "the `other transaction fees` column — chargebacks, shipping holdbacks — " "minus the rows identified as advertising, which move to the " "Advertising line", }, "adjustments": { "formula": "Σ `other` over Adjustment rows", "source": "rows of type `Adjustment` (FBA inventory reimbursements, buyer " "recharges); the amount sits in the `other` column", }, "freight": { "formula": "Σ `other` over Shipping Services rows", "source": "rows of type `Shipping Services` — outward freight billed by Amazon", }, "other_service_charges": { "formula": "Σ `other` over the remaining rows", "source": "the `other` column of rows not classified as storage, freight, " "advertising, or adjustment (e.g. subscription fees)", "note": "If this is unexpectedly large, open Transaction Details and check the " "descriptions — a new Amazon charge type may deserve its own line.", }, "transfers": { "formula": "Σ `total` over Transfer rows", "source": "rows of type `Transfer` — Amazon's bank payouts (negative = paid out to us)", }, "liquidations": { "formula": "Σ `total` over Liquidations rows — memo only", "source": "rows of type `Liquidations` / `Liquidations Adjustments`", "note": "Already included in the lines above; shown separately for visibility, " "never added twice.", }, # ------------------------------------------------- aggregate lines "gross_revenue": { "formula": "Order/product sales + Shipping credits + Gift-wrap credits " "+ Other sales credits + Refunds", "source": "the revenue-group lines above", }, "net_revenue": { "formula": "Gross revenue + every fee line (rebates, tax, selling, FBA, storage, " "advertising, other fees, adjustments, freight, other services)", "source": "every line above except Transfers — i.e. all activity except bank payouts", "note": "Equals the month's accrued receivable movement before payouts.", }, "opening_balance": { "formula": "prior month's closing receivable", "source": "carried forward from the prior closing, or entered from last month's " "workbook on the Opening Balances tab", "note": "Zero on a first-ever closing. Until entered, the roll-forward measures " "only this month's movement (see control C4).", }, "disbursements": { "formula": "Σ payouts RECEIVED by month-end", "source": "a payout counts as received from its BANK-receipt date when Finance has " "entered one (received ⇔ bank date ≤ month-end); otherwise the " "clearing-lag heuristic on Amazon's transfer date (auto mode) or not at " "all (manual mode)", "note": "Amazon's Transfer date is when the payout was initiated — the bank credit " "lands 3-5 working days later. Enter bank dates on the AR Ledger tab.", }, "in_transit_payouts": { "formula": "Σ payouts NOT received by month-end", "source": "payouts Amazon initiated whose bank credit had not arrived by month-end; " "their settlements stay in the receivable", }, "bank_receipt": { "formula": "received ⇔ bank date ≤ month-end", "source": "the date (and amount) Finance records when a payout lands in the bank " "account — overrides the clearing-lag heuristic for that payout", "note": "auto mode: payouts without a receipt fall back to the clearing-lag " "heuristic. manual mode: a payout without a receipt is NOT received. " "Changes apply when the closing is re-processed. If the bank amount " "differs from Amazon's payout, a variance warning is raised on the " "Exceptions tab; the ledger keeps Amazon's amount.", }, "closing_receivable": { "formula": "Opening AR balance + Net revenue − Payouts received", "source": "the roll-forward method — cross-checked against the settlement method " "(control C4)", }, "settlement_closing": { "formula": "ROUND(reserve + additional sales) per marketplace", "source": "`additional sales` = Σ `total` over open (unpaid) settlements, for real " "order account types, excluding Transfers — the workbook's SUMIFS method", "note": "This is the method the Finance workbook uses (USA Jan-26 = 11,110,433) and " "the benchmark figure. FX converts it to USD per marketplace.", }, "reserve": { "formula": "Opening + Sales − Receipts − Refunds − Expenses over PAID settlements (≈ 0)", "source": "a small Finance-maintained reconciliation carry entered per marketplace", }, # ------------------------------------------------- overview / other tabs "closing_receivable_usd": { "formula": "Σ over marketplaces of ROUND(reserve + additional sales) × FX rate, " "+ manual adjustments", "source": "the settlement method per marketplace, converted at the session's " "confirmed FX rates", }, "receivable_orders": { "formula": "Σ `total` over rows in RECEIVABLE settlements", "source": "non-transfer rows of settlements not yet paid out by the cutoff", }, "paid_orders": { "formula": "Σ `total` over rows in PAID settlements", "source": "non-transfer rows of settlements whose payout reached the bank by the cutoff", }, "transfers_total": { "formula": "Σ `total` over every Transfer row", "source": "all bank payouts in the uploaded files, received or in transit", }, "settlement_status": { "formula": "receivable ⇔ settlement id ≥ the paid boundary", "source": "a settlement stays receivable until the Transfer that pays it out is " "dated on/before month-end − clearing-lag; the boundary is the newest " "settlement with a received payout", }, "aging_basis": { "formula": "days past DUE at month-end; due = last activity + 14-day settlement " "cycle + clearing lag", "source": "each receivable settlement's last activity date", "note": "Amazon settles ~biweekly, so a healthy month is ~100% Current. A " "settlement Amazon is holding ages into 1-30/31-60/61-90.", }, # ------------------------------------------------- journal entry (GL lines) "journal_entry": { "formula": "Dr fees & refunds · Cr sales & tax · balancing Dr A/R = net revenue", "source": "the month-end ACCRUAL entry. Positive line totals are credits, negative " "are debits, so debits always equal credits", "note": "Bank receipts (Transfer) are posted separately from bank statements and are " "deliberately not part of this entry. Approval publishes the month to the " "Accounts Summary; re-processing withdraws the sign-off.", }, "Sales": { "formula": "Σ (`product sales` + `shipping credits` + `gift wrap credits`) over non-refund rows", "source": "gross sales value of every order-type row — Credit", }, "Refunds": { "formula": "Σ (`product sales` + `shipping credits` + `gift wrap credits`) over refund rows", "source": f"rows of type {REFUND_TYPES_LABEL} — Debit", }, "Tax": { "formula": "Σ of every tax column, netted", "source": "product/shipping/gift-wrap sales tax + regulatory + promotional-rebate tax " "+ marketplace-withheld + collected — nets ≈ 0 where Amazon remits", }, "FBA Selling Fee": { "formula": "Σ `selling fees`", "source": "referral commissions and variable closing fees — Debit", }, "FBA Storage": { "formula": "Σ `other` over FBA Inventory Fee rows", "source": "monthly + long-term storage fees — Debit", }, "FBA Fee": { "formula": "Σ (`fba fees` + `promotional rebates` + non-advertising `other transaction " "fees` + `regulatory fee` + unclassified `other`)", "source": "the catch-all Amazon fee/adjustment bucket — Debit", "note": "Advertising is broken out to its own line and is NOT in here.", }, "Advertising Cost": { "formula": "Σ (`other` + `other transaction fees`) over advertising rows", "source": "rows whose description reads as advertising (\"Cost of advertising\", " "Sponsored Products, localized variants) — Debit", "note": "Amazon books these as plain `Service Fee`; the description is the only " "signal, and the amount column differs by region.", }, "Inventory Adjustment": { "formula": "manual sheet line (0 unless classified)", "source": "inventory adjustments booked to Sales:Inventory Adjustments", }, "Outward Freight / Shipping": { "formula": "Σ `other` over Shipping Services rows", "source": "outward freight billed by Amazon — Debit", }, "Receivable": { "formula": "−Σ(all lines above) = net revenue", "source": "the balancing figure of the accrual entry — Dr Accounts Receivable", "note": "Equals the AR Ledger's net revenue for the month; bank receipts then " "credit A/R as they arrive.", }, "uploaded_total": { "formula": "Σ `total` over every row of every uploaded file", "source": "identical to receivable + paid + transfers by construction — a " "self-consistency figure, NOT a control (see the Controls tab for the " "checks that can actually fail)", }, }