feat(subs): normalize anchor time to closest iteration before activation

Author: GAlexIHU

openmeter/subscription/repo/mapping.go

@@ -60,7 +60,7 @@ func MapDBSubscription(sub *db.Subscription) (subscription.Subscription, error)
 		Currency:        sub.Currency,
 		BillingCadence:  billingCadence,
 		ProRatingConfig: sub.ProRatingConfig,
-		BillingAnchor:   sub.BillingAnchor,
+		BillingAnchor:   sub.BillingAnchor.UTC(),
 	}, nil
 }
 

openmeter/subscription/repo/subscriptionrepo.go

@@ -110,7 +110,7 @@ func (r *subscriptionRepo) Create(ctx context.Context, sub subscription.CreateSu
 			SetNillableDescription(sub.Description).
 			SetBillablesMustAlign(sub.BillablesMustAlign).
 			SetMetadata(sub.Metadata).
-			SetBillingAnchor(sub.BillingAnchor)
+			SetBillingAnchor(sub.BillingAnchor.UTC())
 
 		if sub.ActiveTo != nil {
 			command = command.SetActiveTo(*sub.ActiveTo)

openmeter/subscription/workflow/service/subscription.go

@@ -14,6 +14,7 @@ import (
 	"github.com/openmeterio/openmeter/pkg/clock"
 	"github.com/openmeterio/openmeter/pkg/framework/transaction"
 	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/timeutil"
 )
 
 func (s *service) CreateFromPlan(ctx context.Context, inp subscriptionworkflow.CreateSubscriptionWorkflowInput, plan subscription.Plan) (subscription.SubscriptionView, error) {
@@ -48,6 +49,29 @@ func (s *service) CreateFromPlan(ctx context.Context, inp subscriptionworkflow.C
 			return def, fmt.Errorf("failed to resolve active from: %w", err)
 		}
 
+		// Let's normalize the billing anchor to the closest iteration based on the cadence
+		billingAnchor := lo.FromPtrOr(inp.BillingAnchor, activeFrom).UTC()
+
+		billingRecurrence, err := timeutil.RecurrenceFromISODuration(lo.ToPtr(plan.ToCreateSubscriptionPlanInput().BillingCadence), billingAnchor)
+		if err != nil {
+			return def, fmt.Errorf("failed to get billing recurrence: %w", err)
+		}
+
+		billingAnchor, err = billingRecurrence.PrevBefore(activeFrom)
+		if err != nil {
+			return def, fmt.Errorf("failed to get billing anchor: %w", err)
+		}
+
+		// When anchor = beforeTime (or falls on iteration boundary), PrevBefore will return an iteration early.
+		oneBefore, err := billingRecurrence.Prev(activeFrom)
+		if err != nil {
+			return def, fmt.Errorf("failed to get one iteration before billing anchor: %w", err)
+		}
+
+		if oneBefore.Equal(billingAnchor) {
+			billingAnchor = activeFrom
+		}
+
 		// Let's create the new Spec
 		spec, err := subscription.NewSpecFromPlan(plan, subscription.CreateSubscriptionCustomerInput{
 			CustomerId:    cust.ID,
@@ -56,7 +80,7 @@ func (s *service) CreateFromPlan(ctx context.Context, inp subscriptionworkflow.C
 			MetadataModel: inp.MetadataModel,
 			Name:          lo.CoalesceOrEmpty(inp.Name, plan.GetName()),
 			Description:   inp.Description,
-			BillingAnchor: lo.FromPtrOr(inp.BillingAnchor, activeFrom).UTC(),
+			BillingAnchor: billingAnchor,
 		})
 
 		if err := subscriptionworkflow.MapSubscriptionErrors(err); err != nil {

openmeter/subscription/workflow/service/subscription_test.go

@@ -28,6 +28,7 @@ import (
 	"github.com/openmeterio/openmeter/pkg/framework/lockr"
 	"github.com/openmeterio/openmeter/pkg/isodate"
 	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/timeutil"
 )
 
 func TestCreateFromPlan(t *testing.T) {
@@ -90,6 +91,41 @@ func TestCreateFromPlan(t *testing.T) {
 				}
 			},
 		},
+		{
+			Name: "Should normalize billing anchor to the closest iteration",
+			Handler: func(t *testing.T, deps testCaseDeps) {
+				ctx, cancel := context.WithCancel(context.Background())
+				defer cancel()
+
+				cad := deps.Plan.ToCreateSubscriptionPlanInput().BillingCadence
+
+				activeFrom := deps.CurrentTime
+
+				billingAnchor := activeFrom.Add(time.Hour)
+
+				cadRec, err := timeutil.RecurrenceFromISODuration(lo.ToPtr(cad), billingAnchor)
+				require.Nil(t, err)
+
+				// Let's set an anchor one hour after the activeFrom, which will then be set to one iteration before
+
+				expectedBillingAnchor, err := cadRec.Prev(billingAnchor)
+				require.Nil(t, err)
+
+				subView, err := deps.WorkflowService.CreateFromPlan(ctx, subscriptionworkflow.CreateSubscriptionWorkflowInput{
+					ChangeSubscriptionWorkflowInput: subscriptionworkflow.ChangeSubscriptionWorkflowInput{
+						Timing: subscription.Timing{
+							Custom: &deps.CurrentTime,
+						},
+					},
+					CustomerID:    deps.Customer.ID,
+					Namespace:     subscriptiontestutils.ExampleNamespace,
+					BillingAnchor: &billingAnchor,
+				}, deps.Plan)
+				require.Nil(t, err)
+
+				require.Equal(t, expectedBillingAnchor, subView.Subscription.BillingAnchor)
+			},
+		},
 	}
 
 	for _, tc := range testCases {

tools/migrate/migrations/20250610125104_subs-billing-anchor.up.sql

@@ -1,2 +1,8 @@
 -- modify "subscriptions" table
-ALTER TABLE "subscriptions" ADD COLUMN "billing_anchor" timestamptz NOT NULL;
+ALTER TABLE "subscriptions" ADD COLUMN "billing_anchor" timestamptz;
+
+-- update all entries to set the billing anchor to the active_from time
+UPDATE "subscriptions" SET "billing_anchor" = "active_from" WHERE "billing_anchor" IS NULL;
+
+-- make the billing anchor not nullable
+ALTER TABLE "subscriptions" ALTER COLUMN "billing_anchor" SET NOT NULL;

tools/migrate/migrations/atlas.sum

@@ -1,4 +1,4 @@
-h1:O4KJp2wgNnSPMGyVIFTLms5dJy1jh5VwwD3vodSIgxc=
+h1:rNbbVrC/sli4lZdHSKmh2/iV0pMvJ4Xu42ZzoQOAOGA=
 20240826120919_init.up.sql h1:tc1V91/smlmaeJGQ8h+MzTEeFjjnrrFDbDAjOYJK91o=
 20240903155435_entitlement-expired-index.up.sql h1:Hp8u5uckmLXc1cRvWU0AtVnnK8ShlpzZNp8pbiJLhac=
 20240917172257_billing-entities.up.sql h1:Q1dAMo0Vjiit76OybClNfYPGC5nmvov2/M2W1ioi4Kw=
@@ -106,4 +106,4 @@ h1:O4KJp2wgNnSPMGyVIFTLms5dJy1jh5VwwD3vodSIgxc=
 20250609172811_billing-split-line-group.up.sql h1:lop1t+ERtU58bCMK9cxgrc51OstEkIVjM2VIQj5x2ko=
 20250609204117_billing-migrate-split-line-groups.up.sql h1:jtPl2Fpkhwut/5WcUz8h2lSxtbjvfRH2/QhbRcJDQzU=
 20250610101736_plan-subscription-billing-cadence.up.sql h1:01Cu9dQMHIEFZuT66Zxo9uWq3fIj57mlqnYkMu7Zobo=
-20250610125104_subs-billing-anchor.up.sql h1:8YpAKGOLEi4tEeQztsEzPTNWmyyqJ77NaKy2JcY6iuE=
+20250610125104_subs-billing-anchor.up.sql h1:oCxmAFVtwo7h+INdbpp2XseR/srBwgCWKUQTjguXjl4=