feat: invoice in advance flat fees on subs creation (#2470)

Author: turip

openmeter/billing/worker/subscription/handlers.go

@@ -4,13 +4,16 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"time"
 
 	"github.com/samber/lo"
+	"github.com/samber/mo"
 
 	"github.com/openmeterio/openmeter/openmeter/billing"
 	"github.com/openmeterio/openmeter/openmeter/customer"
 	"github.com/openmeterio/openmeter/openmeter/subscription"
 	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/currencyx"
 	"github.com/openmeterio/openmeter/pkg/models"
 )
 
@@ -103,3 +106,76 @@ func (h *Handler) HandleInvoiceCreation(ctx context.Context, invoice billing.Eve
 
 	return nil
 }
+
+func (h *Handler) HandleSubscriptionCreated(ctx context.Context, subs subscription.SubscriptionView, asOf time.Time) error {
+	if err := h.SyncronizeSubscription(ctx, subs, asOf); err != nil {
+		return err
+	}
+
+	if subs.Spec.HasBillables() {
+		// Let's check if there are any pending lines that we can invoice now (those will be in-advance fees, so we don't have to wait
+		// for the collection period)
+
+		gatheringInvoices, err := h.billingService.ListInvoices(ctx, billing.ListInvoicesInput{
+			Namespaces:       []string{subs.Subscription.Namespace},
+			Customers:        []string{subs.Customer.ID},
+			ExtendedStatuses: []billing.InvoiceStatus{billing.InvoiceStatusGathering},
+			Currencies:       []currencyx.Code{subs.Spec.Currency},
+			Expand: billing.InvoiceExpand{
+				Lines: true,
+			},
+		})
+		if err != nil {
+			return fmt.Errorf("failed to list gathering invoices: %w", err)
+		}
+
+		now := clock.Now()
+
+		invoicableLines := []string{}
+
+		for _, invoice := range gatheringInvoices.Items {
+			inScopeLines := lo.Filter(invoice.Lines.OrEmpty(), func(line *billing.Line, _ int) bool {
+				if line.Subscription.SubscriptionID != subs.Subscription.ID {
+					return false
+				}
+
+				if line.Status != billing.InvoiceLineStatusValid {
+					return false
+				}
+
+				return !line.InvoiceAt.After(now)
+			})
+
+			if len(inScopeLines) == 0 {
+				continue
+			}
+
+			invoicableLines = append(invoicableLines, lo.Map(inScopeLines, func(line *billing.Line, _ int) string {
+				return line.ID
+			})...)
+		}
+
+		if len(invoicableLines) > 0 {
+			invoices, err := h.billingService.InvoicePendingLines(ctx, billing.InvoicePendingLinesInput{
+				Customer: customer.CustomerID{
+					Namespace: subs.Subscription.Namespace,
+					ID:        subs.Customer.ID,
+				},
+
+				IncludePendingLines: mo.Some(invoicableLines),
+			})
+			if err != nil {
+				return fmt.Errorf("failed to create invoice: %w", err)
+			}
+
+			h.logger.Info("created invoice on subscription creation trigger",
+				"customer_id", subs.Customer.ID,
+				"invoice_ids", lo.Map(invoices, func(inv billing.Invoice, _ int) string {
+					return fmt.Sprintf("%s/%s", inv.Number, inv.ID)
+				}),
+			)
+		}
+	}
+
+	return nil
+}

openmeter/billing/worker/subscription/sync_test.go

@@ -2804,6 +2804,114 @@ func (s *SubscriptionHandlerTestSuite) TestRateCardTaxSync() {
 	}
 }
 
+func (s *SubscriptionHandlerTestSuite) TestInAdvanceInstantBillingOnSubscriptionCreation() {
+	ctx := s.Context
+	clock.FreezeTime(s.mustParseTime("2024-01-01T00:00:00Z"))
+
+	// Given
+	//  we have a subscription with a single phase with an in advance fee
+	// When
+	//  we start the subscription
+	// Then
+	//  the gathering invoice will automatically be invoiced so that the in advance fee is billed (those are always flat fees)
+
+	subsView := s.createSubscriptionFromPlanPhases([]productcatalog.Phase{
+		{
+			PhaseMeta: s.phaseMeta("first-phase", ""),
+			RateCards: productcatalog.RateCards{
+				&productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:  "in-advance",
+						Name: "in-advance",
+						Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+							Amount:      alpacadecimal.NewFromFloat(6),
+							PaymentTerm: productcatalog.InAdvancePaymentTerm,
+						}),
+					},
+					BillingCadence: isodate.MustParse(s.T(), "P1D"),
+				},
+				&productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:     s.APIRequestsTotalFeature.Key,
+						Name:    s.APIRequestsTotalFeature.Key,
+						Feature: &s.APIRequestsTotalFeature,
+						Price: productcatalog.NewPriceFrom(productcatalog.UnitPrice{
+							Amount: alpacadecimal.NewFromFloat(10),
+						}),
+					},
+					BillingCadence: isodate.MustParse(s.T(), "P1D"),
+				},
+			},
+		},
+	})
+
+	s.NoError(s.Handler.HandleSubscriptionCreated(ctx, subsView, clock.Now()))
+
+	invoices, err := s.BillingService.ListInvoices(ctx, billing.ListInvoicesInput{
+		Customers: []string{s.Customer.ID},
+		Expand:    billing.InvoiceExpandAll,
+	})
+	s.NoError(err)
+	s.Len(invoices.Items, 2)
+
+	var gatheringInvoice *billing.Invoice
+	var instantInvoice *billing.Invoice
+
+	for _, invoice := range invoices.Items {
+		if invoice.Status == billing.InvoiceStatusGathering {
+			gatheringInvoice = &invoice
+			continue
+		}
+
+		instantInvoice = &invoice
+	}
+
+	s.NotNil(gatheringInvoice, "gathering invoice should be present")
+	s.NotNil(instantInvoice, "instant invoice should be present")
+
+	s.DebugDumpInvoice("gathering invoice", *gatheringInvoice)
+	s.DebugDumpInvoice("instant invoice", *instantInvoice)
+
+	// Gathering invoice should have the UBP line
+	s.expectLines(*gatheringInvoice, subsView.Subscription.ID, []expectedLine{
+		{
+			Matcher: recurringLineMatcher{
+				PhaseKey: "first-phase",
+				ItemKey:  s.APIRequestsTotalFeature.Key,
+			},
+			Price: mo.Some(productcatalog.NewPriceFrom(productcatalog.UnitPrice{
+				Amount: alpacadecimal.NewFromFloat(10),
+			})),
+			Periods: []billing.Period{
+				{
+					Start: s.mustParseTime("2024-01-01T00:00:00Z"),
+					End:   s.mustParseTime("2024-01-02T00:00:00Z"),
+				},
+			},
+			InvoiceAt: []time.Time{s.mustParseTime("2024-01-02T00:00:00Z")},
+		},
+	})
+
+	// Instant invoice should have the in advance fee
+	s.expectLines(*instantInvoice, subsView.Subscription.ID, []expectedLine{
+		{
+			Matcher: recurringLineMatcher{
+				PhaseKey: "first-phase",
+				ItemKey:  "in-advance",
+			},
+			Qty:       mo.Some[float64](1),
+			UnitPrice: mo.Some[float64](6),
+			Periods: []billing.Period{
+				{
+					Start: s.mustParseTime("2024-01-01T00:00:00Z"),
+					End:   s.mustParseTime("2024-01-02T00:00:00Z"),
+				},
+			},
+			InvoiceAt: []time.Time{s.mustParseTime("2024-01-01T00:00:00Z")},
+		},
+	})
+}
+
 func (s *SubscriptionHandlerTestSuite) expectValidationIssueForLine(line *billing.Line, issue billing.ValidationIssue) {
 	s.Equal(billing.ValidationIssueSeverityWarning, issue.Severity)
 	s.Equal(billing.ImmutableInvoiceHandlingNotSupportedErrorCode, issue.Code)

openmeter/billing/worker/worker.go

@@ -142,7 +142,7 @@ func (w *Worker) eventHandler(opts WorkerOptions) (*grouphandler.NoPublishingHan
 		opts.Router.MetricMeter,
 
 		grouphandler.NewGroupEventHandler(func(ctx context.Context, event *subscription.CreatedEvent) error {
-			return w.subscriptionHandler.SyncronizeSubscription(ctx, event.SubscriptionView, time.Now())
+			return w.subscriptionHandler.HandleSubscriptionCreated(ctx, event.SubscriptionView, time.Now())
 		}),
 		grouphandler.NewGroupEventHandler(func(ctx context.Context, event *subscription.CancelledEvent) error {
 			return w.subscriptionHandler.HandleCancelledEvent(ctx, event)