2b47bd8b10
Centralize billing for all NexaSystems services (NexaCloud, NexaDesk, NexaMaps, custom apps, memberships) on the Odoo 19 Enterprise instance, replacing Lago. The module adds only the metering + integration layer; native sale_subscription / account_accountant / payment_stripe do all the financial work (invoicing, HST, dunning, portal, credit notes, Stripe). Includes: - Design spec (docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md): 6 locked decisions, architecture, data model, usage engine, Lago-shaped API, webhook control loop, NexaCloud pilot, phased dual-run migration. - Module scaffold: 7 fusion.billing.* models (service, account.link, metric, charge, usage, webhook, reconciliation), bearer-auth API controller shell, security ACLs, README. Compiles on Odoo 19.0; engine/API bodies are stubs pending the implementation plan. - CLAUDE.md rule #15: no sale.subscription model in Odoo 19 — a subscription is a sale.order(is_subscription) + sale.subscription.plan (verified live). Task 0 verified: a single Stripe account is shared across NexaCloud and all Lago providers, so no Stripe account/card migration is required. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fusion Centralized Billing (fusion_centralize_billing)
Centralized billing engine that makes this Odoo 19 Enterprise instance the single billing brain for every NexaSystems service — NexaCloud hosting, NexaDesk chat, NexaMaps API, custom apps, and memberships. It replaces Lago and absorbs NexaCloud's home-grown Stripe billing into one customer ledger and one accounting system.
Design spec:
docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.mdStatus: SCAFFOLD. Models + security + the API auth shell are in place and the module installs. The usage engine, full inbound API, and webhook processor are stubs to be implemented from the writing-plans output.
Why this module is small
We build only the metering + integration layer. Everything financial — recurring
invoicing, HST tax, proration, dunning, customer portal, credit notes, Stripe — is
native Odoo Enterprise (sale_subscription, account_accountant, payment_stripe),
already installed and running.
Design decisions (locked)
- Odoo fully replaces Lago (we build the metered-billing engine; Lago is decommissioned last).
- One unified
res.partnerper client; separate invoice per service. - Apps drive, Odoo is the billing system of record — apps call the inbound API (as they call Lago today); Odoo bills and webhooks back.
- Odoo owns the billing catalog; apps own feature entitlements (shared
plan_code). - Pilot = NexaCloud, phased dual-run cutover.
- Aggregate-push usage ingestion (periodic counters, not a raw-event firehose).
Models (fusion.billing.*)
| Model | Purpose |
|---|---|
fusion.billing.service |
One source app; bearer API key (hashed) + webhook config. |
fusion.billing.account.link |
External account id → one res.partner (identity resolution). |
fusion.billing.metric |
Billable metric + aggregation (sum/max/last/unique). |
fusion.billing.charge |
Plan + metric → included quota + overage pricing. |
fusion.billing.usage |
Aggregated per-period usage rollups (idempotent). |
fusion.billing.webhook |
Outbound lifecycle event queue (HMAC + retry). |
fusion.billing.reconciliation |
Dual-run Odoo-vs-app delta during cutover. |
Odoo 19 note (verified): a subscription is a
sale.orderwithis_subscription=True(plan_id→sale.subscription.plan). There is nosale.subscriptionmodel.fusion.billing.usage.subscription_idtherefore points atsale.order.
Inbound API
Lago-shaped REST under /api/billing/v1/*, bearer auth. Endpoints mirror NexaDesk's
existing lago-client.ts so migration is a thin client swap. /health works today;
the rest return 501 until implemented.
Relationship to fusion_api
fusion_api manages outbound provider keys (OpenAI, Maps, Twilio) + cost tracking —
i.e. COGS. This module tracks customer revenue. Complementary: feed fusion_api
cost into margin reporting; reuse its daily-rollup aggregation pattern.
Dependencies
account_accountant, sale_subscription, sale_management, payment_stripe.
Local dev
docker exec odoo-nexa-app odoo -d nexamain -u fusion_centralize_billing --stop-after-init
# tests (once added):
docker exec odoo-nexa-app odoo -d nexamain --test-enable --test-tags /fusion_centralize_billing -u fusion_centralize_billing --stop-after-init
Canadian English, CAD, HST via account.tax. New fields on native models use the x_fc_* prefix.