feat: book invoice accrued for usagebased items (#4144)

Author: turip

.agents/skills/charges/SKILL.md

@@ -126,6 +126,8 @@ Current shared contract details:
 - optional split outputs use pointers; `SplitGatheringLineResult.PostSplitAtLine` is `*billing.GatheringLine`
 - use `billing.ValidateStandardLineIDsMatchExactly(...)` when a charge-side test or helper needs to assert that returned standard-line identities are preserved across a line-engine boundary
 - collection-time errors should be normalized through `billing.NewLineEngineValidationError(...)` instead of rebuilding the validation-issue wrapper at each billing callsite
+- charge line engines are only responsible for invoice-backed charge flows such as `credit_then_invoice`; they are not the execution path for `credit_only` settlement mode
+- because of that boundary, it is acceptable for a charge line engine to return an error when invoked with `credit_only` settlement mode; treat that as a lifecycle misuse rather than adding `credit_only` behavior to the engine
 
 ## Timestamp Normalization
 
@@ -193,6 +195,25 @@ Placement guidance:
 - do not mutate whole intents inside adapters just to normalize currency; if an adapter needs a persistence backstop, keep it local to the `Set*` write
 - when ledger logic derives monetary values from balances, entries, or its own calculations, round those values in ledger code as well; do not rely only on upstream callers
 
+## Zero Invoice Accrual
+
+Invoice accrual uses a non-negative, no-op-aware contract.
+
+Rules:
+
+- negative invoice-accrual amounts are invalid
+- zero invoice-accrual amounts are valid no-ops
+- positive invoice-accrual amounts must produce a non-empty ledger transaction group reference
+- charges-side services should short-circuit zero before calling persistence that expects a real ledger transaction
+- do not persist `invoicedusage.AccruedUsage` rows with an empty `LedgerTransaction.TransactionGroupID`
+
+Current expected behavior:
+
+- `usagebased.OnInvoiceUsageAccruedInput.Validate()` allows zero and rejects only negatives
+- usage-based and flat-fee service/orchestration layers should skip invoice-accrual persistence when the invoice line total is zero
+- ledger handlers may still defensively tolerate zero and return `ledgertransaction.GroupReference{}`
+- when a service proceeds with non-zero invoice accrual, it must require a non-empty transaction group reference before storing accrued usage
+
 ## Realization Helper Subpackages
 
 Use small type-specific realization helper subpackages to keep charge services and state machines from becoming kitchen-sink orchestration layers.

app/common/charges.go

@@ -85,8 +85,16 @@ func NewChargesCreditPurchaseHandler(
 	return ledgerchargeadapter.NewCreditPurchaseHandler(ledgerService, accountResolver, accountService)
 }
 
-func NewChargesUsageBasedHandler(collectorService ledgercollector.Service) usagebased.Handler {
-	return ledgerchargeadapter.NewUsageBasedHandler(collectorService)
+func NewChargesUsageBasedHandler(
+	ledgerService ledger.Ledger,
+	accountResolver ledger.AccountResolver,
+	accountService ledgeraccount.Service,
+	collectorService ledgercollector.Service,
+) usagebased.Handler {
+	return ledgerchargeadapter.NewUsageBasedHandler(ledgerService, transactions.ResolverDependencies{
+		AccountService:    accountResolver,
+		SubAccountService: accountService,
+	}, collectorService)
 }
 
 func NewChargesFlatFeeAdapter(
@@ -309,8 +317,8 @@ func newChargesRegistry(
 
 	collectorService := NewChargesCollectorService(ledgerService, accountResolver, accountService)
 	flatFeeHandler := NewChargesFlatFeeHandler(ledgerService, accountResolver, accountService, collectorService)
+	usageBasedHandler := NewChargesUsageBasedHandler(ledgerService, accountResolver, accountService, collectorService)
 	creditPurchaseHandler := NewChargesCreditPurchaseHandler(ledgerService, accountResolver, accountService)
-	usageBasedHandler := NewChargesUsageBasedHandler(collectorService)
 
 	flatFeeAdapter, err := NewChargesFlatFeeAdapter(db, logger, metaAdapter)
 	if err != nil {

app/common/customerbalance.go

@@ -1,36 +1,19 @@
 package common
 
 import (
-	"context"
 	"log/slog"
 
 	"github.com/google/wire"
 
 	"github.com/openmeterio/openmeter/app/config"
-	"github.com/openmeterio/openmeter/openmeter/billing/charges"
-	chargeadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/adapter"
-	"github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee"
-	flatfeeadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee/adapter"
-	flatfeeservice "github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee/service"
-	lineageadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/lineage/adapter"
-	lineageservice "github.com/openmeterio/openmeter/openmeter/billing/charges/lineage/service"
-	"github.com/openmeterio/openmeter/openmeter/billing/charges/meta"
-	metaadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/meta/adapter"
-	"github.com/openmeterio/openmeter/openmeter/billing/charges/usagebased"
-	usagebasedadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/usagebased/adapter"
-	usagebasedservice "github.com/openmeterio/openmeter/openmeter/billing/charges/usagebased/service"
 	"github.com/openmeterio/openmeter/openmeter/billing/rating"
 	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
 	"github.com/openmeterio/openmeter/openmeter/ledger"
 	ledgeraccount "github.com/openmeterio/openmeter/openmeter/ledger/account"
-	ledgerchargeadapter "github.com/openmeterio/openmeter/openmeter/ledger/chargeadapter"
-	ledgercollector "github.com/openmeterio/openmeter/openmeter/ledger/collector"
 	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
-	"github.com/openmeterio/openmeter/openmeter/ledger/transactions"
 	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
 	"github.com/openmeterio/openmeter/openmeter/streaming"
 	"github.com/openmeterio/openmeter/pkg/framework/lockr"
-	"github.com/openmeterio/openmeter/pkg/pagination"
 )
 
 var CustomerBalance = wire.NewSet(
@@ -55,165 +38,14 @@ func NewCustomerBalanceService(
 		return customerbalance.NewNoopService(), nil
 	}
 
-	metaAdapter, err := metaadapter.New(metaadapter.Config{
-		Client: db,
-		Logger: logger,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	lineageAdapter, err := lineageadapter.New(lineageadapter.Config{
-		Client: db,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	lineageService, err := lineageservice.New(lineageservice.Config{
-		Adapter: lineageAdapter,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	searchAdapter, err := chargeadapter.New(chargeadapter.Config{
-		Client: db,
-		Logger: logger,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	flatFeeAdapter, err := flatfeeadapter.New(flatfeeadapter.Config{
-		Client:      db,
-		Logger:      logger,
-		MetaAdapter: metaAdapter,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	collectorService := ledgercollector.NewService(ledgercollector.Config{
-		Ledger: historicalLedger,
-		Dependencies: transactions.ResolverDependencies{
-			AccountService:    accountResolver,
-			SubAccountService: accountService,
-		},
-	})
-
-	flatFeeService, err := flatfeeservice.New(flatfeeservice.Config{
-		Adapter:     flatFeeAdapter,
-		Handler:     ledgerchargeadapter.NewFlatFeeHandler(historicalLedger, transactions.ResolverDependencies{AccountService: accountResolver, SubAccountService: accountService}, collectorService),
-		Lineage:     lineageService,
-		MetaAdapter: metaAdapter,
-		Locker:      locker,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	usageAdapter, err := usagebasedadapter.New(usagebasedadapter.Config{
-		Client:      db,
-		Logger:      logger,
-		MetaAdapter: metaAdapter,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	usageService, err := usagebasedservice.New(usagebasedservice.Config{
-		Adapter:                 usageAdapter,
-		Handler:                 ledgerchargeadapter.NewUsageBasedHandler(collectorService),
-		Lineage:                 lineageService,
-		Locker:                  locker,
-		MetaAdapter:             metaAdapter,
-		CustomerOverrideService: billingRegistry.Billing,
-		FeatureService:          featureConnector,
-		RatingService:           ratingService,
-		StreamingConnector:      streamingConnector,
-	})
-	if err != nil {
-		return nil, err
-	}
-
 	return customerbalance.New(customerbalance.Config{
 		AccountResolver:   accountResolver,
 		SubAccountService: accountService,
-		ChargesService:    customerBalanceChargeStore{search: searchAdapter, flatFeeService: flatFeeService, usageBasedService: usageService},
-		UsageBasedService: usageService,
+		ChargesService:    billingRegistry.Charges.Service,
+		UsageBasedService: billingRegistry.Charges.UsageBasedService,
 	})
 }
 
 func NewCustomerBalanceFacade(service customerbalance.FacadeService) (*customerbalance.Facade, error) {
 	return customerbalance.NewFacade(service)
 }
-
-type customerBalanceChargeStore struct {
-	search            charges.ChargesSearchAdapter
-	flatFeeService    flatfee.Service
-	usageBasedService usagebased.Service
-}
-
-func (s customerBalanceChargeStore) ListCharges(ctx context.Context, input charges.ListChargesInput) (pagination.Result[charges.Charge], error) {
-	searchResult, err := s.search.ListCharges(ctx, input)
-	if err != nil {
-		return pagination.Result[charges.Charge]{}, err
-	}
-
-	flatFeeIDs := make([]string, 0, len(searchResult.Items))
-	usageBasedIDs := make([]string, 0, len(searchResult.Items))
-
-	for _, item := range searchResult.Items {
-		switch item.Type {
-		case meta.ChargeTypeFlatFee:
-			flatFeeIDs = append(flatFeeIDs, item.ID.ID)
-		case meta.ChargeTypeUsageBased:
-			usageBasedIDs = append(usageBasedIDs, item.ID.ID)
-		}
-	}
-
-	flatFeeCharges, err := s.flatFeeService.GetByIDs(ctx, flatfee.GetByIDsInput{
-		Namespace: input.Namespace,
-		IDs:       flatFeeIDs,
-		Expands:   input.Expands,
-	})
-	if err != nil {
-		return pagination.Result[charges.Charge]{}, err
-	}
-
-	usageBasedCharges, err := s.usageBasedService.GetByIDs(ctx, usagebased.GetByIDsInput{
-		Namespace: input.Namespace,
-		IDs:       usageBasedIDs,
-		Expands:   input.Expands,
-	})
-	if err != nil {
-		return pagination.Result[charges.Charge]{}, err
-	}
-
-	chargesByID := make(map[string]charges.Charge, len(flatFeeCharges)+len(usageBasedCharges))
-
-	for _, charge := range flatFeeCharges {
-		chargesByID[charge.ID] = charges.NewCharge(charge)
-	}
-
-	for _, charge := range usageBasedCharges {
-		chargesByID[charge.ID] = charges.NewCharge(charge)
-	}
-
-	items := make([]charges.Charge, 0, len(searchResult.Items))
-	for _, item := range searchResult.Items {
-		charge, ok := chargesByID[item.ID.ID]
-		if !ok {
-			continue
-		}
-
-		items = append(items, charge)
-	}
-
-	return pagination.Result[charges.Charge]{
-		Page:       searchResult.Page,
-		TotalCount: searchResult.TotalCount,
-		Items:      items,
-	}, nil
-}

openmeter/billing/adapter/invoice.go

@@ -846,6 +846,8 @@ func (a *adapter) IsAppUsed(ctx context.Context, appID app.AppID) error {
 				billing.StandardInvoiceStatusGathering,
 				billing.StandardInvoiceStatusIssuingSyncing,
 				billing.StandardInvoiceStatusIssuingSyncFailed,
+				billing.StandardInvoiceStatusIssuingChargeBooking,
+				billing.StandardInvoiceStatusIssuingChargeBookingFailed,
 				billing.StandardInvoiceStatusIssued,
 				billing.StandardInvoiceStatusPaymentProcessingPending,
 				billing.StandardInvoiceStatusPaymentProcessingFailed,

openmeter/billing/charges/creditpurchase/lineengine/engine.go

@@ -83,6 +83,10 @@ func (e *Engine) OnStandardInvoiceCreated(_ context.Context, input billing.OnSta
 	return input.Lines, nil
 }
 
+func (e *Engine) OnInvoiceIssued(_ context.Context, _ billing.OnInvoiceIssuedInput) error {
+	return nil
+}
+
 func (e *Engine) CalculateLines(input billing.CalculateLinesInput) (billing.StandardLines, error) {
 	if input.Invoice.ID == "" {
 		return nil, fmt.Errorf("invoice id is required")

openmeter/billing/charges/flatfee/lineengine/engine.go

@@ -79,12 +79,18 @@ func (e *Engine) BuildStandardInvoiceLines(ctx context.Context, input billing.Bu
 		return nil, err
 	}
 
-	gatheringLinesByID := make(map[string]billing.GatheringLine, len(input.GatheringLines))
-	for _, gatheringLine := range input.GatheringLines {
-		gatheringLinesByID[gatheringLine.ID] = gatheringLine
+	return e.CalculateLines(billing.CalculateLinesInput{
+		Invoice: input.Invoice,
+		Lines:   stdLines,
+	})
+}
+
+func (e *Engine) OnStandardInvoiceCreated(ctx context.Context, input billing.OnStandardInvoiceCreatedInput) (billing.StandardLines, error) {
+	if err := input.Validate(); err != nil {
+		return nil, fmt.Errorf("validating input: %w", err)
 	}
 
-	for _, stdLine := range stdLines {
+	for _, stdLine := range input.Lines {
 		chargeID := stdLine.ChargeID
 		if chargeID == nil {
 			return nil, fmt.Errorf("flat fee standard line[%s]: charge id is required", stdLine.ID)
@@ -103,12 +109,7 @@ func (e *Engine) BuildStandardInvoiceLines(ctx context.Context, input billing.Bu
 			return nil, fmt.Errorf("getting flat fee charge for line[%s]: %w", stdLine.ID, err)
 		}
 
-		sourceGatheringLine, ok := gatheringLinesByID[stdLine.ID]
-		if !ok {
-			return nil, fmt.Errorf("flat fee standard line[%s]: source gathering line not found", stdLine.ID)
-		}
-
-		realizations, err := e.flatFeeService.PostLineAssignedToInvoice(ctx, charge, sourceGatheringLine)
+		realizations, err := e.flatFeeService.PostLineAssignedToInvoice(ctx, charge, *stdLine)
 		if err != nil {
 			return nil, fmt.Errorf("allocating credits for line[%s]: %w", stdLine.ID, err)
 		}
@@ -118,18 +119,15 @@ func (e *Engine) BuildStandardInvoiceLines(ctx context.Context, input billing.Bu
 		}
 	}
 
-	return e.CalculateLines(billing.CalculateLinesInput{
-		Invoice: input.Invoice,
-		Lines:   stdLines,
-	})
+	return e.CalculateLines(billing.CalculateLinesInput(input))
 }
 
 func (e *Engine) OnCollectionCompleted(_ context.Context, input billing.OnCollectionCompletedInput) (billing.StandardLines, error) {
 	return input.Lines, nil
 }
 
-func (e *Engine) OnStandardInvoiceCreated(_ context.Context, input billing.OnStandardInvoiceCreatedInput) (billing.StandardLines, error) {
-	return input.Lines, nil
+func (e *Engine) OnInvoiceIssued(_ context.Context, _ billing.OnInvoiceIssuedInput) error {
+	return nil
 }
 
 func (e *Engine) CalculateLines(input billing.CalculateLinesInput) (billing.StandardLines, error) {

openmeter/billing/charges/flatfee/service.go

@@ -26,7 +26,7 @@ type FlatFeeService interface {
 }
 
 type InvoiceLifecycleHooks interface {
-	PostLineAssignedToInvoice(ctx context.Context, charge Charge, line billing.GatheringLine) (creditrealization.Realizations, error)
+	PostLineAssignedToInvoice(ctx context.Context, charge Charge, line billing.StandardLine) (creditrealization.Realizations, error)
 	PostInvoiceIssued(ctx context.Context, charge Charge, lineWithHeader billing.StandardLineWithInvoiceHeader) error
 	PostInvoicePaymentAuthorized(ctx context.Context, charge Charge, lineWithHeader billing.StandardLineWithInvoiceHeader) error
 	PostInvoicePaymentSettled(ctx context.Context, charge Charge, lineWithHeader billing.StandardLineWithInvoiceHeader) error

openmeter/billing/charges/flatfee/service/invoice.go

@@ -13,8 +13,7 @@ import (
 	"github.com/openmeterio/openmeter/pkg/framework/transaction"
 )
 
-// TODO: Once we have proper UBP handling this should happen on the already converted StandardLine but for now we should be fine with this approach.
-func (s *service) PostLineAssignedToInvoice(ctx context.Context, charge flatfee.Charge, line billing.GatheringLine) (creditrealization.Realizations, error) {
+func (s *service) PostLineAssignedToInvoice(ctx context.Context, charge flatfee.Charge, line billing.StandardLine) (creditrealization.Realizations, error) {
 	if charge.State.AmountAfterProration.IsZero() {
 		return nil, nil
 	}
@@ -27,7 +26,7 @@ func (s *service) PostLineAssignedToInvoice(ctx context.Context, charge flatfee.
 
 		input := flatfee.OnAssignedToInvoiceInput{
 			Charge:            charge,
-			ServicePeriod:     line.ServicePeriod,
+			ServicePeriod:     line.Period.ToClosedPeriod(),
 			PreTaxTotalAmount: currencyCalculator.RoundToPrecision(charge.State.AmountAfterProration),
 		}
 		if err := input.Validate(); err != nil {
@@ -64,6 +63,10 @@ func (s *service) PostInvoiceIssued(ctx context.Context, charge flatfee.Charge,
 			return fmt.Errorf("postInvoiceIssued: line is nil")
 		}
 
+		if lineWithHeader.Line.Totals.Total.IsZero() {
+			return nil
+		}
+
 		ledgerTransactionRef, err := s.handler.OnInvoiceUsageAccrued(ctx, flatfee.OnInvoiceUsageAccruedInput{
 			Charge:        charge,
 			ServicePeriod: lineWithHeader.Line.Period.ToClosedPeriod(),

openmeter/billing/charges/meta/triggers.go

@@ -8,4 +8,5 @@ var (
 	TriggerNext                Trigger = "next"
 	TriggerInvoiceCreated      Trigger = "invoice_created"
 	TriggerCollectionCompleted Trigger = "collection_completed"
+	TriggerInvoiceIssued       Trigger = "invoice_issued"
 )