Gathering invoices not being created despite having all required components

[Maloquiin]

Issue Description

We have a complete OpenMeter billing setup with all necessary components, but gathering invoices are not being created automatically. We're looking for guidance on what might be missing or misconfigured.

Current Setup

Our OpenMeter instance includes:

• ✅ Billing Profile with progressive billing enabled and collection interval set to 2 hours
• ✅ Customer with USD currency and proper subject attribution
• ✅ Active Subscription linked to a usage-based plan
• ✅ Meter collecting usage events successfully
• ✅ Feature properly configured and linked to the meter
• ✅ Plan with usage-based rate cards ($0.017 per unit, monthly billing cadence)
• ✅ Usage Events being sent and tracked (100+ units of usage recorded)
• ✅ Entitlements working correctly (showing usage consumption and balance changes)

Expected vs Actual Behavior

Expected:

• Gathering invoices should be created automatically to track upcoming charges for the current billing period
• We should see gathering invoices when querying /api/v1/billing/invoices?statuses=gathering

Actual:

• No gathering invoices are created (totalCount: 0)
• Manual invoice creation via /api/v1/billing/invoices/invoice returns "invoice_create_no_lines" error
• All other billing components work correctly

Questions

1. What are the specific requirements for gathering invoice creation? Are there any conditions we might be missing?

2. Does the billing cadence or collection timing affect when gathering invoices are created? Our current billing period just started today.

3. Are there any configuration flags or settings that need to be enabled beyond progressive billing for automatic gathering invoice creation?

4. Should we expect gathering invoices to appear immediately after usage events are recorded, or is there a delay/threshold?

Environment

• OpenMeter version: 1.0.0-beta.219
• Progressive billing: Enabled
• Collection interval: PT2H
• Payment method: send_invoice

Any insights or troubleshooting steps would be greatly appreciated!

Please Help!

[turip]

Hi Maloquiin!

Thank you for this detailed question. 🙇

My first guess would be that billing worker is not running on your environment. Let me quickly propose a PR with updated helm charts (and quickstart).

Regarding your questions regarding gathering invoices:

• Gathering invoices are created on subscription start, and will contain all items for the next billing period (and in-advance items for the N+1th billing period).
• Metered events are not directly triggering anything in regard gathering invoices, but gathering invoices will show the current amount based on any data ingested.
• All the cadence settings are reflected on the invoice, but gathering invoices are provisioned after subscription start in a few seconds.
• Progressive billing is not something that would matter from the gathering invoice perspective, it only allows you to invoice customers earlier.

[Maloquiin]

Quick question: Is the "billing worker" a separate/new entity that doesn't exist in the current Helm chart?
I can see I have balanceWorker, sinkWorker, and notificationService in my values.yaml, but no billingWorker section.
Thanks!

[turip]

This pull request contains the updated charts and everything required: #3235

Once it's in I can release a new OpenMeter version or you can use the latest tag.

For a fully functional billing setup, you need the following to be operational:

• billing-worker: responsible for event driven billing tasks, such as gathering invoice creation on subscription changes etc.
• subscription-sync job: reconciler job, failsafe for anything billing worker misses
• collection job: gathering invoice -> draft invoice creation job (the first invoice is automatically created, this only creates the 2nd and later invoices)
• advance job: advances invoices that are waiting for auto approval if needed

These are all included in the helm chart.

[turip]

A new release has been tagged with the updated chart: https://github.com/openmeterio/openmeter/releases/tag/v1.0.0-beta.220

[Maloquiin]

Thank you so much - everything is working perfectly now! Gathering invoices are being created as expected. Great work! 🎉