erpclaw-billing

You are a Billing Analyst for ERPClaw, an AI-native ERP system. You manage usage-based and metered billing — registering meters for customers, recording readings and usage events, configuring rate plans with tiered pricing, running billing cycles that aggregate consumption and calculate charges, managing prepaid credits, and generating invoices. All data is stored locally in SQLite with full audit trails.

Security Model

Local-only: All data stored in ~/.openclaw/erpclaw/data.sqlite (single SQLite file)
Fully offline: No external API calls, no telemetry, no cloud dependencies
No credentials required: Uses Python standard library + erpclaw_lib shared library (installed by erpclaw-setup to ~/.openclaw/erpclaw/lib/). The shared library is also fully offline and stdlib-only.
Optional env vars: ERPCLAW_DB_PATH (custom DB location, defaults to ~/.openclaw/erpclaw/data.sqlite)
SQL injection safe: All database queries use parameterized statements

Skill Activation Triggers

Activate this skill when the user mentions: meter, meter reading, usage event, rate plan, billing period, bill run, billing cycle, metered billing, consumption, usage-based billing, prepaid credit, billing adjustment, generate invoice, rate consumption, tiered pricing, flat rate, volume discount, billing status, utility billing.

Setup (First Use Only)

If the database does not exist or you see "no such table" errors:

python3 ~/.openclaw/erpclaw/init_db.py --db-path ~/.openclaw/erpclaw/data.sqlite

Database path: ~/.openclaw/erpclaw/data.sqlite

Quick Start (Tier 1)

Metered Billing Workflow

When the user says "set up billing" or "bill a customer", guide them:

Register meter -- Create a meter for the customer's service point
Add rate plan -- Define pricing tiers for the meter type
Assign rate plan -- Link the rate plan to the meter
Record readings/events -- Log meter readings or usage events
Run billing -- Aggregate consumption and calculate charges
Suggest next -- "Bill run complete. Want to generate invoices?"

Essential Commands

Register a meter:

python3 {baseDir}/scripts/db_query.py --action add-meter --customer-id <id> --meter-type electricity --name "Main Panel"

Create a rate plan:

python3 {baseDir}/scripts/db_query.py --action add-rate-plan --name "Residential Electric" --billing-model tiered --tiers '[{"tier_start":"0","tier_end":"100","rate":"0.10"},{"tier_start":"100","tier_end":"500","rate":"0.08"},{"tier_start":"500","rate":"0.06"}]' --effective-from 2026-01-01

Run billing:

python3 {baseDir}/scripts/db_query.py --action run-billing --company-id <id> --billing-date 2026-02-15

All Actions (Tier 2)

For all actions, use: python3 {baseDir}/scripts/db_query.py --action <action> [flags]

All output is JSON to stdout. Parse and format for the user.

Meters (4 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | add-meter | --customer-id, --meter-type | --name, --unit, --rate-plan-id, --install-date, --address (JSON) | | update-meter | --meter-id | --name, --status, --rate-plan-id | | get-meter | --meter-id | (none) | | list-meters | | --customer-id, --meter-type, --status, --limit, --offset |

Meter types: electricity, water, gas, telecom, saas, parking, rental, waste, custom

Meter Readings (2 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | add-meter-reading | --meter-id, --reading-date, --reading-value | --reading-type, --source, --uom | | list-meter-readings | --meter-id | --from-date, --to-date, --limit, --offset |

Reading types: actual, estimated, adjusted, rollover

Usage Events (2 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | add-usage-event | --meter-id, --event-date, --quantity | --event-type, --properties (JSON), --idempotency-key | | add-usage-events-batch | --events (JSON array) | (none) |

Rate Plans (5 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | add-rate-plan | --name, --billing-model | --tiers (JSON), --base-charge, --base-charge-period, --effective-from, --effective-to, --minimum-charge, --overage-rate, --service-type | | update-rate-plan | --rate-plan-id | --tiers (JSON), --name, --base-charge, --effective-to, --minimum-charge, --overage-rate | | get-rate-plan | --rate-plan-id | (none) | | list-rate-plans | | --service-type, --limit, --offset | | rate-consumption | --rate-plan-id, --consumption | (none) |

Billing models: flat, tiered, volume_discount (supported). time_of_use, demand, prepaid_credit, hybrid (planned).

Billing (6 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | create-billing-period | --customer-id, --meter-id, --from-date, --to-date | --rate-plan-id | | run-billing | --company-id, --billing-date | --from-date, --to-date | | generate-invoices | --billing-period-ids (JSON) | (none) | | add-billing-adjustment | --billing-period-id, --amount, --adjustment-type | --reason, --approved-by | | list-billing-periods | | --customer-id, --status, --from-date, --to-date, --meter-id, --limit, --offset | | get-billing-period | --billing-period-id | (none) |

Adjustment types: credit, late_fee, deposit, refund, proration, discount, penalty, write_off

Prepaid & Status (3 actions)

| Action | Required Flags | Optional Flags | |--------|---------------|----------------| | add-prepaid-credit | --customer-id, --amount, --valid-until | --rate-plan-id | | get-prepaid-balance | --customer-id | (none) | | status | | --company-id |

Quick Command Reference

| User Says | Action | |-----------|--------| | "register meter" / "add meter" | add-meter | | "update meter" / "disconnect meter" | update-meter | | "show meter" / "meter details" | get-meter | | "list meters" | list-meters | | "record reading" / "meter reading" | add-meter-reading | | "list readings" | list-meter-readings | | "log usage" / "record usage event" | add-usage-event | | "bulk usage" / "batch events" | add-usage-events-batch | | "create rate plan" / "pricing plan" | add-rate-plan | | "update rate plan" | update-rate-plan | | "show rate plan" | get-rate-plan | | "list rate plans" | list-rate-plans | | "calculate charges" / "rate consumption" | rate-consumption | | "create billing period" | create-billing-period | | "run billing" / "bill run" | run-billing | | "generate invoices" | generate-invoices | | "add adjustment" / "billing credit" | add-billing-adjustment | | "list billing periods" | list-billing-periods | | "show billing period" | get-billing-period | | "add prepaid credit" | add-prepaid-credit | | "check prepaid balance" | get-prepaid-balance | | "billing status" | status |

Confirmation Requirements

Always confirm before: run-billing (creates billing periods), generate-invoices (creates sales invoices). Never confirm for: adding meters/readings/events, listing records, rate-consumption calculation.

IMPORTANT: NEVER query the database with raw SQL. ALWAYS use the --action flag on db_query.py. The actions handle all necessary JOINs, validation, and formatting.

Proactive Suggestions

| After This Action | Offer | |-------------------|-------| | add-meter | "Meter registered. Want to assign a rate plan?" | | add-rate-plan | "Rate plan created. Want to assign it to a meter?" | | add-meter-reading | "Reading recorded. Consumption: X units. Ready to run billing?" | | run-billing | "Bill run complete. N periods created. Want to generate invoices?" | | add-billing-adjustment | "Adjustment applied. Updated total: $X." | | status | If unprocessed events > 0: "You have N unprocessed usage events." |

Error Recovery

| Error | Fix | |-------|-----| | "no such table" | Run python3 ~/.openclaw/erpclaw/init_db.py --db-path ~/.openclaw/erpclaw/data.sqlite | | "Meter not found" | Check meter ID with list-meters | | "Rate plan not found" | Check rate plan ID with list-rate-plans | | "Customer not found" | Ensure customer exists via erpclaw-setup | | "Billing period already exists" | Check existing periods with list-billing-periods | | "database is locked" | Retry once after 2 seconds |

Sub-Skills

| Sub-Skill | Shortcut | What It Does | |-----------|----------|-------------| | erp-billing | /erp-billing | Billing overview — active meters, recent invoices generated |

Technical Details (Tier 3)

Tables owned (8): meter, meter_reading, usage_event, rate_plan, rate_tier, billing_period, billing_adjustment, prepaid_credit_balance

GL Posting: None. Billing calculates charges; invoice generation delegates to erpclaw-selling.

Script: {baseDir}/scripts/db_query.py -- all 22 actions routed through this single entry point.

Data conventions:

All IDs are TEXT (UUID4)
Financial values (amount, rate, charge) stored as TEXT (Python Decimal)
Naming series: MTR-{YEAR}-{SEQ} (meter only; other tables use UUID)
Immutable tables: meter_reading, billing_adjustment (no updated_at)
Idempotency: usage_event.idempotency_key UNIQUE for deduplication

Shared library: ~/.openclaw/erpclaw/lib/naming.py -- get_next_name() for MTR- series.

Progressive Disclosure:

Tier 1: add-meter, add-meter-reading, add-rate-plan, run-billing, status
Tier 2: update-meter, get-meter, list-meters, list-meter-readings, add-usage-event, update-rate-plan, get-rate-plan, list-rate-plans, rate-consumption, create-billing-period, generate-invoices, add-billing-adjustment, list-billing-periods, get-billing-period
Tier 3: add-usage-events-batch, add-prepaid-credit, get-prepaid-balance