Metered Billing
Record physical cumulative meter readings, approve their usage deltas and review intervals before explicitly creating native draft customer invoices. The app connects a metering point to its customer, site, unit, billing product and flat unit tariff. Odoo Accounting remains the source of financial truth.
Installation and edition
Install corvus_metered_billing on Odoo 20.0 using the standard administrator
installation process. Place the addon on your configured addons path, update
the Apps list and install Metered Billing. Direct dependencies are Accounting
(account) and Discuss (mail); no external driver or service is required.
Tested on Odoo 20.0 Enterprise: installation with and without demo data, focused workflow and access checks, and native HTML report rendering passed. Community has not been qualified on a Community runtime. Depending on standard Community addons does not itself establish edition qualification.
Normal data includes cubic-metre and kWh unit references, period and adjustment sequences, access roles and menus. Demo data is optional. It creates fictional Riverside Court meters, readings, accounting fixtures and draft documents. It does not post invoices, send invoices or change your shared accounting configuration. Demo account codes and the demo sales journal are for examples, not a chart-of-accounts recommendation.
Roles and company boundaries
Assign the Metered Billing role in Settings > Users. The installer administrator receives Manager access by default.
- Reader: read meter configuration, enter readings and edit draft readings. Readers cannot approve readings, change tariffs or access billing periods.
- Billing Officer: Reader capabilities plus approve readings, review usage periods, create draft invoices and view adjustments. This role includes the native Invoicing role; native accounting access is deliberate.
- Manager: Billing Officer capabilities plus meter setup, removing unused drafts, resetting uninvoiced reviews and creating reasoned adjustments.
All business records are restricted to allowed companies. Linked customers, products, journals and documents are checked for company consistency. No public portal or external reading endpoint is provided.
Accounting and meter setup
- Configure your company's native Accounting setup, including a sales journal and customer receivable accounts. Configure each billing product's income account, unit, customer taxes and relevant fiscal positions. Accounting configuration is not replaced by this module.
- Open Metered Billing > Meters > New. Give the metering point a stable reference, such as RIV-W-04. A point represents a logical site measurement location, even when its physical device is replaced.
- Select customer, site, company and optional initial device serial/reference.
- Select a native billing product and exactly matching counter unit. Supplied units are optional examples; you can use another native unit matching your product. There is no automatic conversion between a meter and its product.
- Set currency and a nonnegative flat unit tariff. Tariffs use native Product Price precision. Whether the price includes tax is determined by the native product taxes, not by a separate module tax setting.
- Select an optional native sales journal; otherwise Odoo selects its normal sales journal when a document is created. Set a rollover limit only if the counter has a known wrap point, for example 100000.
- Record access/reading instructions and assign the appropriate user roles.
The company and counter unit cannot change after readings exist. Archive a metering point when it is no longer used; points with history cannot be deleted. Future tariff/customer/product changes affect newly reviewed periods. Already reviewed periods retain their billing snapshot. When changing a product, keep its unit consistent with the existing meter unit.
Record and approve readings
Open Readings > New or use a meter's Readings smart button. Select the meter, actual observation timestamp and cumulative displayed value. Optional photos support the reading; an image is not required. Add relevant notes. Timestamps are displayed in the user's timezone. Values and consumption use native Product Unit decimal precision.
A Billing Officer clicks Approve Reading. Approvals must follow strict chronological order for each meter; two readings cannot share a timestamp. The first approved normal reading establishes a baseline with zero usage. Later normal readings calculate current value minus previous approved value. The previous reading, computed consumption, approving user and time are retained. A normal reading cannot decrease the counter.
Approved readings, photographs and event details cannot be edited or deleted. There is no silent approval through an import or a status-field edit. Repeated approval is rejected. Draft entries can be corrected before approval.
Counter events and formulas
An event describes what happened between the previous approved reading and the current observation. Each event requires an explanation. The first baseline must use Normal reading.
Normal reading
Usage = current counter - previous counter. Example: 1125 - 1000 = 125 units.
Counter rollover
Usage = counter limit - previous counter + current counter. The counter limit is the exclusive point that wraps to zero. Example: 100000 - 99920 + 40 = 120 kWh. The previous and current values must be below the limit, and the current value must be lower than the previous value. Only one wrap between observations is represented. Multiple unknown wraps cannot be inferred.
Counter reset
Record the old counter's final value and the reset counter's opening value. Usage = old final - previous approved + current - new opening. Example: old final 60, previous 40, current 15 and new opening 0 yield 35 kWh. The old final cannot be lower than the previous value; the current cannot be lower than the new opening value. Explain the reset and its supporting service reference. The same explicit rebaselining may document an approved transcription correction, but state clearly in the reason when no physical reset occurred; use a billing adjustment for any already billed difference.
Meter replacement
Use the same two-segment formula as reset and record the replacement device's serial/reference. Example: previous 15, old final 25, new opening 5 and current 18 yield 23 kWh. The logical metering point remains the same; the approved event retains the new device identity and reason. This is not an automatic equipment or warranty-management workflow.
Review a billing period
Open Billing Periods > New, select a meter and two approved readings. The opening timestamp must precede the closing timestamp. The interval includes all approved usage deltas after the opening and through the closing reading, written as (opening, closing]. It does not simply subtract the two counters when intervening rollover/reset/replacement events exist.
The Included Usage tab lists every included reading and event. A draft can be edited. Click Review Period after inspecting the evidence. The action checks for overlapping Reviewed or Invoice Created periods and freezes the customer, billing product, unit, currency, flat tariff and selected journal. Adjacent periods may share a boundary reading; the earlier interval bills the delta ending at that boundary, and the next interval begins after it.
A Manager may Reset Review for an uninvoiced Reviewed period, edit it and review again. This uses current meter configuration for the new snapshot. Once an invoice exists, the period cannot be reset or have its interval changed. Use a linked adjustment instead. Direct edits to derived interval dates and status are blocked, including imported/context defaults.
Worked usage-to-invoice example
Riverside Court Unit 4 has water readings of 1000 on 1 October and 1125 on 1 November. Its flat tariff is 2.40 currency units per cubic metre.
- Approve the two readings in chronological order. The closing reading's approved usage is 125 cubic metres.
- Create a period between them and inspect Included Usage.
- Click Review Period. Confirm the frozen customer, product, unit, currency and tariff shown on the form.
- Click Create Draft Invoice. Odoo creates a native customer invoice with quantity 125 and unit price 2.40. With no taxes in this fictional example, the amount is 300.00. Real taxes follow your native product/customer setup.
- Use the Invoice smart button. Finance checks accounts, tax/fiscal position, dates, payment terms and totals, then posts or sends through the normal Accounting workflow when appropriate.
Creation is explicit. Repeating Create Draft Invoice returns the existing invoice rather than creating another. All generated invoices and credits have automatic posting disabled and stay draft. Nothing is sent to a customer by the module. Zero-usage periods may create zero-quantity draft documents; finance decides whether they should be retained, posted or cancelled.
Product income accounts, taxes and customer fiscal positions are computed by native Accounting at invoice creation. Native tax and currency rounding apply. The period does not implement a parallel tax engine. A tariff is frozen at review, while current native tax/account configuration applies when the draft is created. Native finance review remains available afterward.
Corrections and native credit notes
For a period with an existing invoice, a Manager clicks Record Adjustment. Enter a signed usage quantity and a specific reason with supporting evidence. The unit is the original period unit.
- Positive quantities add usage and create another native draft customer invoice at the original period tariff.
- Negative quantities credit usage and create a native draft credit note, with its reversal reference linked to the original invoice.
Click Create Correction Draft. For the water example, a -5 cubic-metre adjustment produces a 5-unit credit at 2.40, or 12.00 before tax. Corrections reuse the original native usage line's mapped taxes; native Accounting still calculates tax amounts and currency rounding. Original readings and original period consumption remain unchanged. The linked adjustment explains the difference. A repeated action opens its existing document.
Before generating a correction, the module checks the original and prior module-generated correction documents. They must retain a single usage line with the expected quantity, product, unit and tariff, no discount, and the same customer, company and currency. Changes to tax/account configuration can be reviewed natively; changed usage identities or amounts must be resolved in Accounting first. This prevents a native quantity edit from making a later module credit exceed the actual source. Total generated corrections cannot credit more usage than the original quantity plus prior additions.
Cancelled source or correction documents must be resolved in Accounting before another module correction is created. A correction can reference an original draft; finance must review both documents together and decide the appropriate posting/cancellation treatment. The module does not make that accounting decision automatically. Do not delete linked source documents: their history is retained through restrictive links.
An adjustment whose document already exists is immutable. Record a further reasoned adjustment if needed. To correct future counter continuity after an approved transcription error, use an explicitly documented rebaseline event; adjusting an invoice alone does not rewrite the physical reading history.
Registers, unbilled work and reports
Meters can be searched by reference, site or customer and grouped by site or customer. Archived metering points remain available through the Archived filter. The Readings and Billing Periods smart buttons open scoped records.
Readings can be searched by meter or replacement device reference. To Approve shows drafts; Counter Events isolates rollover/reset/replacement entries. Group by meter or event and filter by observation date.
Billing Periods displays interval dates, consumption, unit, frozen tariff, currency, native invoice state and period state. Unbilled Periods shows Draft and Reviewed periods; Ready to Invoice shows Reviewed only. Invoice Created means a native document exists, not that it has been posted or paid. Counter units and currencies are not combined into misleading register totals.
Usage Adjustments shows correction quantity, reason and linked document. Pending Corrections and Usage Credits filters support desk follow-up.
Use Print > Meter Usage Statement on a period for a native QWeb statement with opening/closing readings, included usage deltas, event explanations, reviewed tariff and linked invoices/adjustments. It is usage evidence, not a tax invoice, calibration certificate or substitute for the native financial document.
Native HTML report rendering has been verified. PDF output requires a working native Odoo PDF engine and has not been qualified for this release.
Upgrade preservation
Back up your database and filestore before a module upgrade using the normal Odoo process. Supplied units and document sequences are protected reference data intended to retain edits to their names, sequence prefixes and padding. After an upgrade, verify your reference settings, approved reading history, reviewed snapshots and source document links before resuming billing. An ordinary upgrade is not an instruction to replay approvals or create invoices again.
Do not uninstall while meter history is required. Uninstalling removes module models and records; retain a proper backup/export according to your records policy.
Troubleshooting
Approval is unavailable. Readers can enter data; a Billing Officer or Manager approves it. Check the user's company and role.
The counter decreased. Select and document the actual rollover, reset or replacement event. Do not invent a wrap or device change merely to remove the error. Verify the observation and supporting values first.
A timestamp is rejected. Approve in chronological order and keep one reading per meter/time. An older draft cannot be inserted behind an already approved later observation; preserve the issue in a documented correction.
The period overlaps another. Inspect existing Reviewed and Invoice Created intervals. Use adjacent endpoints or reset an uninvoiced review where justified. Do not duplicate an interval to recreate an invoice.
The draft invoice cannot be created. Review the period first and verify native sales journal, income account, customer receivable account, allowed company, currency and user invoicing rights. Native Accounting validation messages should be resolved in Accounting setup.
The period says Invoice Created but the invoice is draft/cancelled. These are separate states. Open the existing invoice and handle its accounting lifecycle there. The module will not generate a second original invoice.
A correction is refused after finance edited the invoice. Compare the source's customer, currency and single usage line with the frozen period. The module will not silently credit a different quantity/rate or a discounted line. Resolve the mismatch or perform the appropriate correction directly in native Accounting, retaining explanatory notes on the period.
The app cannot see another company's meter. Select an allowed company or ask an administrator to review access. Company restrictions are intentional.
PDF generation fails. Ask your Odoo administrator to check the native PDF engine and server report configuration. Native HTML rendering has been verified; server PDF generation has not been qualified for this release.
Limits and support
Manual cumulative readings and flat unit tariffs only. No smart-meter API, automatic recurring invoice scheduler, subscription engine, tiered pricing, time-of-use tariff, meter calibration or jurisdictional billing certification. One rollover per observation interval is represented; unknown wraps are not estimated. Approvals and invoice creation are deliberate user actions.
Corvus Nexus Technologies LTD
Website: https://corvusnexus.com
Support: support@corvusnexus.com
License: Odoo Proprietary License v1.0 (OPL-1).
Availability
This guide covers the Odoo 20 package. Older-version packages are not part of this release.