usage_billing_review v1.0.0

name: "usage_billing_review" description: "Reviewing metered usage bills before payment or rebilling: reconciling usage exports to invoice quantities, checking tier math, proration, and minimums against the pricing terms, and flagging overcharges with the recalculated amount. Use when a usage-based, metered, API, cloud, or consumption invoice needs checking, when a client will be rebilled for usage, or when a vendor bill looks too high."

Usage Billing Review

Purpose

Recalculate a metered bill from the raw usage and the pricing terms, then compare it line by line to the invoice. The output is a verdict a finance reviewer can act on: pay it, dispute a named amount with the math attached, or hold it pending data the vendor must supply. The review works in both directions. As a buyer, it catches overcharges before payment. As a seller or agency, it proves a rebill is clean before a client sees it.

Workflow

1. Collect the three inputs. Get the invoice (every line, not just the total), the usage export for the same period (CSV with event id, timestamp, and quantity per row where the vendor offers it), and the pricing terms that were in force for that period (signed contract, order form, or a captured pricing page with its date). If any one of the three is missing, say which one and stop at a partial review. A total compared to a total proves nothing.
2. Extract the terms onto the worksheet. Copy assets/review-worksheet.md and fill the terms section word for word: meter and unit divisor, aggregation method, pricing mode, tiers, included units, fixed fees, minimum and its scope, discounts, credits, and the proration rule. Rates come from the terms in hand, never from memory of what a vendor usually charges.
3. Reconcile the quantity first. Sum the usage export per meter and compare it to the invoiced quantity before touching price. Use bin/recalc.py with period bounds: it dedupes on event id, counts duplicates removed and out of period rows, and reports all three numbers. Split any quantity gap by day, then by dimension. Work the full check list in references/reconciliation-checks.md: aggregation, unit conversion, included units, duplicates, gaps, boundaries, and late events.
4. Recalculate the money. Write one spec JSON per meter and run the calculator. Modes: flat, graduated, and volume, with per tier flat amounts, included units, a fixed flat fee, a minimum, a percentage discount, and credits, applied in that order. Then pass the invoiced amount and read the variance and verdict. Example, graduated tiers of 5 at 7 USD, next 5 at 6.50 USD, rest at 6 USD, quantity 20: python3 bin/recalc.py --spec examples/spec-graduated.json --usage examples/usage-20.csv --invoiced 140 Result: recalculated 127.50 USD, variance 12.50 USD, verdict overcharged. The same run prints the per tier split (35.00 + 32.50 + 60.00) that goes into the dispute. Watch the units in the spec: included units are counted in raw export units, and tier limits are counted in rated units after the unit divisor is applied. A price per 1,000 calls with a first tier of 1,000,000 calls is written as a divisor of 1000 and a tier limit of 1000. The shipped per thousand example (6,000,000 calls) recalculates to 4,800.00 USD and matches its invoice. For a fixed fee that changed mid period, use the proration mode instead: python3 bin/recalc.py --prorate --old-fee 20 --new-fee 40 --period-start 2026-09-01 --period-end 2026-10-01 --change-date 2026-09-16 Result: 10.00 USD credit for the unused old fee, 20.00 USD charge for the remaining new fee, 10.00 USD net adjustment, each line shown separately.
5. Classify every variance. Match means the recalculation ties to the cent. Explained residual means rounding or grouping moved the number and the report names the cause and the size. Overcharge or undercharge means a term was applied wrong: name the term, quote it, and give the corrected amount. Set the materiality line the reviewer gave you before classifying; with no line given, flag any variance and label its size plainly.
6. Write the disposition. Pay as invoiced, pay the undisputed part and dispute the rest, or hold pending vendor data. For a dispute, fill assets/dispute-note.md with the invoice line, the quoted term, and the recalculated amount for each item. For a rebill, run the rebilling check in the reference file: every passed-on line traces to a vendor or recalculated line, any markup sits on its own line, and the client total ties.

Output Contract

• A filled worksheet per invoice, from assets/review-worksheet.md.
• Per meter: raw quantity, duplicates removed, out of period rows, included units, billable quantity, the tier breakdown, the recalculated total, the invoiced total, the variance in money and percent, and a verdict of match, overcharged, or undercharged.
• An invoice level roll-up: sum of recalculated meters, other lines checked separately (fixed fees, taxes), total variance, and the explained residual kept apart from the disputed amount.
• Findings list: each finding names the check that caught it, the evidence (invoice line, usage rows, contract clause), the amount, and a confidence label of proven by recalculation, likely, or needs vendor data.
• A disposition: amount approved for payment, amount disputed, and, when disputing, a filled dispute note ready to send.
• A list of checks skipped and why, and of terms that could not be verified from the documents in hand.

Operating Rules

1. Accuracy rule: every factual claim must be verified via web search or a primary source. Never invent numbers, dates, quotes, or events. Unverifiable gets cut or framed as opinion. No confident unverified claims, ever. In this skill that means every rate, tier, and rule in the recalculation traces to the contract, order form, or captured pricing page for that period.
2. Quantity before price. Most usage bill errors are quantity errors (duplicates, wrong aggregation, wrong period, wrong divisor) wearing a price costume. Prove the quantity first.
3. Graduated and volume are different math. Graduated prices each block at its own tier rate and sums the blocks. Volume applies one rate, set by total quantity, to all units. The word tiered in a contract does not settle which one applies. Read the rate clause, test both if it is ambiguous, and report the ambiguity instead of picking silently.
4. Usage charges and fixed fees prorate differently. Usage in a shortened period is normally charged as accrued, with no proration. Fixed fees, seats, and platform fees are where proration math applies: credit the unused old fee and charge the remaining new fee as separate lines. State the day count rule you used.
5. Minimums pay the higher number. Compute actual, compare it to the minimum, and the bill is the higher of the two. Check the scope of the minimum (per meter, per product, or account wide) and its period. A shortfall against a minimum is a contract term, not an overcharge, and the report must say so when that is the finding.
6. Order of operations is part of the answer: rating, fixed fees, minimum, percentage discount, credits, floor at zero. If the vendor applies a different order, recalculate in the vendor order and show the difference. Never hide the order you used.
7. Small residuals get explained, not disputed. Rounding at different report granularity and charges grouped under different lines can move report totals without changing what is owed. Reconcile totals first, explain line moves second, dispute only what survives both steps.
8. Rounding in the calculator is Decimal, half up to cents, applied at tier subtotals and the final total. If the contract specifies a different rounding rule or bills fractional cents, state the gap instead of forcing a match.
9. This review is bookkeeping verification, not legal advice. It can prove a bill disagrees with the stated terms. Whether to withhold payment, and what a dispute window allows, depends on the contract. Read the dispute window from the contract in hand and flag it; never quote a window from memory.
10. Do not pay, dispute, or contact the vendor on the strength of this skill alone. The deliverable is the verified worksheet and a ready to send note. The human sends it.
11. Write plainly. No em dashes. No marketing phrasing. Numbers with their math shown beat adjectives every time.