ent/schema/customer.go (1)

82-87: ParentCustomerID column is defined appropriately; consider indexing or a self-edge if lookups grow

The parent_customer_id field definition (varchar(50), nillable + optional) is consistent with how you’re modeling it elsewhere in ent. If you expect frequent queries like “get all children of parent X”, it may be worth adding:

• An index on parent_customer_id (plus tenant/environment if needed), and/or
• A self-referential ent edge for more convenient traversal and stronger FK semantics.

These are optional design improvements and can be deferred until usage patterns justify them.

docs/invoicing-customer-id.md (2)

52-66: Clarify how RecalculateTaxesOnInvoice derives its customer ID

Here you explain that RecalculateTaxesOnInvoice() “uses invoice's existing CustomerID directly,” while later in the impact analysis you summarize it as “uses invoicing customer ID.” That’s logically true only because invoice.CustomerID is set to the invoicing customer at creation.

To avoid confusion for future readers, consider tightening the wording to explicitly say that tax recalculation uses invoice.CustomerID (which for new flows is the invoicing customer), and does not re-fetch the subscription. This keeps behavior crystal‑clear if flows around CustomerID ever change.

---

318-324: Double‑check “No database migration needed” claim

This section states that no DB migration is needed because the field already exists in the schema. Given this PR also wires invoicing_customer_id into ent schema/migrate and introduces a new edge, please confirm that:

• The column and FK truly pre‑exist in all supported environments, and
• No new DDL is being introduced in this or a related migration.

If any migration is required (even a lightweight one), it’s worth updating this note so ops/dev teams aren’t surprised.

ent/schema/subscription.go (1)

179-182: Edge definition correctly binds the invoicing customer relationship.

The invoicing_customer edge properly uses Unique() for M2O cardinality and Field("invoicing_customer_id") to bind to the foreign key column.

Consider adding an index on invoicing_customer_id in the Indexes() function if you anticipate frequent queries filtering by this field (e.g., "find all subscriptions for a given invoicing customer"). This would improve query performance for such lookups.

// Example addition to Indexes():
index.Fields("tenant_id", "environment_id", "invoicing_customer_id", "status").
    Annotations(entsql.IndexWhere("invoicing_customer_id IS NOT NULL AND status = 'published'")),

internal/repository/ent/customer.go (1)

76-76: Consider adding validation for ParentCustomerID relationships.

While the implementation correctly uses SetNillableParentCustomerID, there's no validation to prevent potential issues such as:

• Circular references (customer A → B → A)
• Referencing a non-existent parent customer
• Setting a customer as its own parent

Consider adding validation in the service layer or as a database constraint. Would you like me to help generate validation logic for these scenarios?

internal/service/subscription.go (1)

293-294: EnableTrueUp propagation into the domain model is straightforward

Copying req.EnableTrueUp onto sub.EnableTrueUp before persistence cleanly exposes the new flag to downstream billing logic. Just ensure this behavior matches any ent‑level DefaultEnableTrueUp so there’s no divergence between API and schema defaults.

internal/api/dto/subscription.go (1)

189-190: EnableTrueUp flag is added without unexpected API behavior

Introducing enable_true_up as a plain bool (no omitempty) is safe and backward compatible; existing clients that omit it will default to false. If the intended default is ever non‑false, you’ll want to mirror that here in Validate() or via a documented API default.

internal/service/billing.go (1)

544-591: Significant code duplication in true-up logic.

The commitment true-up logic at lines 544-591 is nearly identical to lines 991-1037 in CalculateUsageChargesForPreview. This violates DRY principles and creates a maintenance burden where future changes need to be applied in both places.

Consider extracting the true-up logic into a shared helper method:

+func (s *billingService) addCommitmentTrueUpIfNeeded(
+	ctx context.Context,
+	sub *subscription.Subscription,
+	usage *dto.GetUsageBySubscriptionResponse,
+	periodStart, periodEnd time.Time,
+	usageCharges *[]dto.CreateInvoiceLineItemRequest,
+	totalUsageCost *decimal.Decimal,
+) {
+	commitmentAmount := lo.FromPtr(sub.CommitmentAmount)
+	overageFactor := lo.FromPtr(sub.OverageFactor)
+	hasCommitment := commitmentAmount.GreaterThan(decimal.Zero) && overageFactor.GreaterThan(decimal.NewFromInt(1))
+
+	if !hasCommitment || usage.HasOverage || !sub.EnableTrueUp {
+		return
+	}
+
+	remainingCommitment := s.calculateRemainingCommitment(usage, commitmentAmount)
+	if !remainingCommitment.GreaterThan(decimal.Zero) {
+		return
+	}
+
+	planDisplayName := ""
+	for _, item := range sub.LineItems {
+		if item.PlanDisplayName != "" {
+			planDisplayName = item.PlanDisplayName
+			break
+		}
+	}
+
+	precision := types.GetCurrencyPrecision(sub.Currency)
+	roundedRemainingCommitment := remainingCommitment.Round(precision)
+	commitmentUtilized := commitmentAmount.Sub(roundedRemainingCommitment)
+
+	trueUpLineItem := dto.CreateInvoiceLineItemRequest{
+		EntityID:        lo.ToPtr(sub.PlanID),
+		EntityType:      lo.ToPtr(string(types.SubscriptionLineItemEntityTypePlan)),
+		PriceType:       lo.ToPtr(string(types.PRICE_TYPE_FIXED)),
+		PlanDisplayName: lo.ToPtr(planDisplayName),
+		DisplayName:     lo.ToPtr(fmt.Sprintf("%s True Up", planDisplayName)),
+		Amount:          roundedRemainingCommitment,
+		Quantity:        decimal.NewFromInt(1),
+		PeriodStart:     &periodStart,
+		PeriodEnd:       &periodEnd,
+		PriceID:         lo.ToPtr(types.GenerateUUIDWithPrefix(types.UUID_PREFIX_PRICE)),
+		Metadata: types.Metadata{
+			"is_commitment_trueup": "true",
+			"description":          "Remaining commitment amount for billing period",
+			"commitment_amount":    commitmentAmount.String(),
+			"commitment_utilized":  commitmentUtilized.String(),
+		},
+	}
+
+	*usageCharges = append(*usageCharges, trueUpLineItem)
+	*totalUsageCost = totalUsageCost.Add(roundedRemainingCommitment)
+}

Also applies to: 991-1037

internal/service/invoice_test.go (2)

1691-1702: Test assertions inside nil check may silently pass on failures.

Both tests wrap assertions in if got != nil { ... } blocks, but this means if CreateSubscriptionInvoice returns nil for an unexpected reason, the test will pass silently without verifying the core functionality. The tests call s.NoError(err) before the nil check, but a zero-amount invoice scenario (which returns nil) would skip all customer ID assertions.

Consider making the assertion more explicit about expectations:

 s.NoError(err)
-if got != nil {
+if got == nil {
+    s.T().Log("Invoice was nil (likely zero-amount), consider adding line items to subscription for full test coverage")
+    return
+}
 s.NotEmpty(got.ID)
 // Invoice should have invoicing customer ID, not subscription customer ID
 s.Equal(invoicingCustomer.ID, got.CustomerID, "Invoice should use invoicing customer ID")
 // ... remaining assertions
-}

Also applies to: 1751-1761

---

1662-1662: Test subscription created without line items may result in zero-amount invoice.

The test creates a subscription without line items ([]*subscription.SubscriptionLineItem{}), which likely results in a zero-amount invoice that returns nil. This means the core assertion about invoicingCustomer.ID == got.CustomerID may never actually execute.

Consider adding line items to ensure the invoice is created:

-s.NoError(s.GetStores().SubscriptionRepo.CreateWithLineItems(s.GetContext(), subscriptionWithInvoicing, []*subscription.SubscriptionLineItem{}))
+lineItems := []*subscription.SubscriptionLineItem{
+    {
+        ID:              types.GenerateUUIDWithPrefix(types.UUID_PREFIX_SUBSCRIPTION_LINE_ITEM),
+        SubscriptionID:  subscriptionWithInvoicing.ID,
+        CustomerID:      subscriptionWithInvoicing.CustomerID,
+        EntityID:        s.testData.plan.ID,
+        EntityType:      types.SubscriptionLineItemEntityTypePlan,
+        PriceID:         s.testData.prices.apiCalls.ID,
+        PriceType:       s.testData.prices.apiCalls.Type,
+        InvoiceCadence:  types.InvoiceCadenceAdvance, // Ensures charges at period start
+        DisplayName:     "API Calls",
+        Quantity:        decimal.NewFromInt(1),
+        Currency:        subscriptionWithInvoicing.Currency,
+        BillingPeriod:   subscriptionWithInvoicing.BillingPeriod,
+        BaseModel:       types.GetDefaultBaseModel(s.GetContext()),
+    },
+}
+s.NoError(s.GetStores().SubscriptionRepo.CreateWithLineItems(s.GetContext(), subscriptionWithInvoicing, lineItems))

internal/service/subscription_test.go (1)

4610-4921: Invoicing‑customer tests are directionally good; consider making invoice creation deterministic

The new tests around invoicing customer ID (period processing, auto‑cancellation, billing‑period cron) correctly:

• Create a distinct invoicing customer.
• Attach InvoicingCustomerID on subscriptions.
• Assert invoices and cancellations respect that ID where invoices exist.

Right now several assertions are guarded by if len(invoices) > 0 and effectively become no‑ops when no invoice is produced, so regressions in invoice generation would still let tests pass. If you want stronger guarantees, consider:

• Adding minimal line items/usage so a subscription invoice is always created in these tests; and/or
• Asserting that at least one invoice exists for these scenarios.

This is optional but would turn these into hard correctness tests rather than best‑effort checks.

internal/service/customer.go (4)

35-58: Parent‑customer assignment rules are coherent; a couple of edge behaviors to be aware of

The combination of:

• CreateCustomer checks that a chosen parent (by ID or external ID) is not itself a child.
• UpdateCustomer using validateParentCustomerAssignment only when ParentCustomerID actually changes.
• validateParentCustomerAssignment enforcing:
  • No hierarchy changes when the customer has non‑cancelled subscriptions.
  • No self‑parenting.
  • Parent must be top‑level (no parent of its own).
  • A customer that already has children cannot become a child.

gives you a clean “two‑level” hierarchy (root + direct children) and prevents re‑parenting when active subscriptions or existing children would make it ambiguous. That all looks logically sound.

Two behavioral notes (not necessarily bugs):

1. Detaching a parent uses empty string semantics
   Because you only enter this block when req.ParentCustomerID != nil, callers must pass "" (not nil) to clear the parent. If ParentCustomerID is omitted (nil), no hierarchy change occurs. Make sure the API docs / clients are aligned with this contract.

2. No concurrent‑safety at the DB level
   These validations happen via separate reads (SubRepo.List, CustomerRepo.Get, CustomerRepo.List) before the final update. Concurrent updates could, in theory, slip between the checks and the update. If stronger guarantees are required later, this logic might want to live in a transaction and/or be backed by DB‑level constraints.

Overall the implementation is fine; consider documenting the “empty string clears parent” behavior externally.

Also applies to: 342-361, 579-633

---

194-217: GetCustomer parent expansion is correct but recursively calls itself

Wrapping the repo result into dto.CustomerResponse and, when ParentCustomerID is set, calling GetCustomer again for the parent produces the expected expanded structure (ParentCustomer filled).

Given your hierarchy rules disallow nested parents and parent‑customers from having parents, recursion depth is effectively bounded to 1, so this is safe. If you ever relax those rules, you may want to introduce a max‑depth or cycle‑detection guard to avoid pathological recursion.

---

226-302: Bulk parent expansion in GetCustomers is efficient; minor nit on attach path

Using filter.GetExpand().Validate(CustomerExpandConfig), collecting unique ParentCustomerIDs, fetching them with a single List call, and then attaching from a lookup map is a good pattern that avoids N+1 queries.

One tiny optimization you could consider is to skip the “attach parent customers” loop entirely when parentCustomersByID is nil/empty (currently you always iterate response and just never hit the map key). It’s negligible, so only worth changing if you touch this code again.

---

660-707: GetUpcomingCreditGrantApplications flow looks reasonable; verify ListByCustomerID semantics

The new method correctly:

• Verifies the customer exists.
• Uses SubscriptionService.ListByCustomerID to gather all subscriptions.
• Returns an empty, well‑formed response when there are none.
• Delegates to SubscriptionService.GetUpcomingCreditGrantApplications with the collected IDs.

Two small points:

• This constructs a new SubscriptionService per call; that’s fine for now, but if this endpoint becomes hot you might consider injecting a SubscriptionService into customerService instead of recreating it.
• The code assumes ListByCustomerID returns a flat slice of subscriptions, not a paginated wrapper. If that method’s contract ever changes, this code would silently break, so it’s worth double‑checking that assumption.

Functionally this looks good.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: omkar273
Repo: flexprice/flexprice PR: 652
File: internal/service/billing.go:1454-1477
Timestamp: 2025-10-18T10:22:48.348Z
Learning: In `internal/service/billing.go`, the `GetCustomerEntitlements` function passes `subscriptions[0].ID` to `AggregateEntitlements` as a fallback subscription ID. This is acceptable because customers typically have a single subscription, and the subscription ID parameter is only used as fallback metadata in `EntitlementSource` objects, not for business logic or filtering.

Learnt from: omkar273
Repo: flexprice/flexprice PR: 652
File: internal/service/subscription.go:3495-3534
Timestamp: 2025-10-17T21:53:42.505Z
Learning: In `internal/service/subscription.go`, when adding multiple-type addons to a subscription, existing active line items are intentionally reused rather than creating new line items for each addon association. The addon occurrences are tracked via separate `AddonAssociation` records, but billing happens through the shared `SubscriptionLineItem`. This is the expected behavior and should not be flagged as an issue.