feat(deleter): clear or report org delete blockers up front

The delete first checks everything that blocks it and returns all the
reasons together as one failed_precondition response: a running
subscription on a paid plan (the caller downgrades it to the standard
plan), unpaid (open or uncollectible) invoices, and a negative token
balance which support has to settle. When nothing blocks, subscriptions
still running on the standard plan are canceled immediately with
unbilled usage invoiced on the spot, and the invoice check runs again
so a final invoice still blocks the delete. Unused tokens do not block:
the delete forfeits them and writes the amount to an audit record. An
already-deleted org returns not found before any checks run. Invoice
checks always sync from the billing provider first so the decision is
made on fresh data.

Author: whoAbhishekSah

billing/invoice/invoice.go

@@ -43,6 +43,9 @@ const (
 	DraftState State = "draft"
 	OpenState  State = "open"
 	PaidState  State = "paid"
+	// UncollectibleState marks an invoice the provider has written off; it
+	// can still be paid.
+	UncollectibleState State = "uncollectible"
 )
 
 type Invoice struct {

cmd/serve.go

@@ -587,7 +587,7 @@ func buildAPIDependencies(
 	cascadeDeleter := deleter.NewCascadeDeleter(organizationService, projectService, resourceService,
 		groupService, membershipService, policyService, roleService, invitationService, userService, userPATService,
 		serviceUserService, customerService, subscriptionService, invoiceService, checkoutService,
-		creditService, orgKycService,
+		creditService, orgKycService, planService, cfg.Billing.AccountConfig.DefaultPlan,
 	)
 
 	// we should default it with a stdout logger repository as postgres can start to bloat really fast

core/audit/audit.go

@@ -97,6 +97,7 @@ const (
 
 	BillingAccountDetailsUpdatedEvent EventName = "app.billing.account.details.updated"
 	BillingCheckoutDeletedEvent       EventName = "app.billing.checkout.deleted"
+	BillingTokensForfeitedEvent       EventName = "app.billing.tokens.forfeited"
 )
 
 var systemEvents = []EventName{
@@ -113,6 +114,7 @@ var systemEvents = []EventName{
 	OrgDeletedEvent,
 	OrgDisabledEvent,
 	BillingCheckoutDeletedEvent,
+	BillingTokensForfeitedEvent,
 }
 
 func IsSystemEvent(event EventName) bool {

core/deleter/deleter.go

@@ -1,7 +1,38 @@
 package deleter
 
-import "fmt"
+import "strings"
 
-var (
-	ErrDeleteNotAllowed = fmt.Errorf("deletion not allowed for billed accounts")
+// Reasons an organization delete can be blocked. The API error carries
+// them as violation types, so a client can tell the reasons apart
+// without reading the message text.
+const (
+	BlockerActiveSubscription   = "ACTIVE_SUBSCRIPTION"
+	BlockerUnpaidInvoice        = "UNPAID_INVOICE"
+	BlockerNegativeTokenBalance = "NEGATIVE_TOKEN_BALANCE"
 )
+
+// Blocker is one reason an organization cannot be deleted right now.
+type Blocker struct {
+	// Type is one of the Blocker* constants.
+	Type string
+	// Subject is the id of the entity behind the reason.
+	Subject string
+	// Message says what blocks the delete and how to clear it.
+	Message string
+}
+
+// BlockedError carries every blocker the up-front check found, so the
+// caller gets one checklist instead of discovering blockers one retry at
+// a time.
+type BlockedError struct {
+	OrgID    string
+	Blockers []Blocker
+}
+
+func (e *BlockedError) Error() string {
+	msgs := make([]string, 0, len(e.Blockers))
+	for _, b := range e.Blockers {
+		msgs = append(msgs, b.Message)
+	}
+	return "organization cannot be deleted yet: " + strings.Join(msgs, "; ")
+}

core/deleter/service.go

@@ -5,6 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"slices"
+	"strconv"
 
 	"github.com/raystack/frontier/core/audit"
 
@@ -16,6 +18,10 @@ import (
 
 	"github.com/raystack/frontier/billing/customer"
 
+	"github.com/raystack/frontier/billing/plan"
+
+	"github.com/raystack/frontier/billing/subscription"
+
 	"github.com/raystack/frontier/core/organization"
 
 	"github.com/raystack/frontier/internal/bootstrap/schema"
@@ -34,10 +40,6 @@ import (
 	"github.com/raystack/frontier/core/serviceuser"
 )
 
-const (
-	DisableDeleteIfBilled = true
-)
-
 type ProjectService interface {
 	List(ctx context.Context, flt project.Filter) ([]project.Project, error)
 	DeleteModel(ctx context.Context, id string) error
@@ -98,11 +100,14 @@ type CustomerService interface {
 }
 
 type SubscriptionService interface {
+	List(ctx context.Context, filter subscription.Filter) ([]subscription.Subscription, error)
+	Cancel(ctx context.Context, id string, immediate bool) (subscription.Subscription, error)
 	DeleteByCustomer(ctx context.Context, customr customer.Customer) error
 }
 
 type InvoiceService interface {
 	List(ctx context.Context, flt invoice.Filter) ([]invoice.Invoice, error)
+	SyncWithProvider(ctx context.Context, customr customer.Customer) error
 	DeleteByCustomer(ctx context.Context, customr customer.Customer) error
 }
 
@@ -112,13 +117,18 @@ type CheckoutService interface {
 }
 
 type CreditService interface {
+	GetBalance(ctx context.Context, accountID string) (int64, error)
 	DeleteByAccountID(ctx context.Context, accountID string) error
 }
 
 type KycService interface {
 	DeleteKyc(ctx context.Context, orgID string) error
 }
 
+type PlanService interface {
+	GetByID(ctx context.Context, id string) (plan.Plan, error)
+}
+
 type Service struct {
 	projService        ProjectService
 	orgService         OrganizationService
@@ -137,6 +147,13 @@ type Service struct {
 	checkoutService    CheckoutService
 	creditService      CreditService
 	kycService         KycService
+	planService        PlanService
+	// defaultPlan is the billing.customer.default_plan config value: the
+	// plan orgs start on. It holds the plan's name or its uuid, the lookup
+	// resolves both. A subscription on this plan may still be running when
+	// the org is deleted; any other plan blocks the delete until the
+	// caller downgrades it
+	defaultPlan string
 }
 
 func NewCascadeDeleter(orgService OrganizationService, projService ProjectService,
@@ -148,7 +165,8 @@ func NewCascadeDeleter(orgService OrganizationService, projService ProjectServic
 	serviceUserService ServiceUserService,
 	customerService CustomerService, subService SubscriptionService,
 	invoiceService InvoiceService, checkoutService CheckoutService,
-	creditService CreditService, kycService KycService) *Service {
+	creditService CreditService, kycService KycService,
+	planService PlanService, defaultPlan string) *Service {
 	return &Service{
 		projService:        projService,
 		orgService:         orgService,
@@ -167,6 +185,8 @@ func NewCascadeDeleter(orgService OrganizationService, projService ProjectServic
 		checkoutService:    checkoutService,
 		creditService:      creditService,
 		kycService:         kycService,
+		planService:        planService,
+		defaultPlan:        defaultPlan,
 	}
 }
 
@@ -217,9 +237,16 @@ func (d Service) DeleteGroup(ctx context.Context, id string) error {
 // leaves the org owned and the delete can simply be run again. Every step
 // treats already-deleted data as success for the same reason.
 func (d Service) DeleteOrganization(ctx context.Context, id string) error {
-	// check if delete is allowed
-	if err := d.canDelete(ctx, id); err != nil {
-		return fmt.Errorf("%s: %w", err.Error(), ErrDeleteNotAllowed)
+	// an org that is already gone has nothing left to check or tear down;
+	// disabled orgs stay deletable
+	if _, err := d.orgService.Get(ctx, id); err != nil && !errors.Is(err, organization.ErrDisabled) {
+		return err
+	}
+
+	// clear what we can and collect what still blocks the delete, before
+	// touching any data
+	if err := d.ensureDeletable(ctx, id); err != nil {
+		return err
 	}
 
 	// delete all billing accounts
@@ -364,6 +391,22 @@ func (d Service) DeleteCustomers(ctx context.Context, id string) error {
 				slog.WarnContext(ctx, "failed to write audit log", "error", err, "event", audit.BillingCheckoutDeletedEvent, "checkout_id", ch.ID)
 			}
 		}
+		// tokens still on the account are forfeited by this delete, so
+		// record the amount before the transactions are removed
+		balance, err := d.creditService.GetBalance(ctx, c.ID)
+		if err != nil {
+			return fmt.Errorf("failed to delete org while checking balance of billing account[%s]: %w", c.ID, err)
+		}
+		if balance > 0 {
+			if err := auditLogger.LogWithAttrs(audit.BillingTokensForfeitedEvent, audit.Target{
+				ID:   c.ID,
+				Type: "billing_account",
+			}, map[string]string{
+				"amount": strconv.FormatInt(balance, 10),
+			}); err != nil {
+				slog.WarnContext(ctx, "failed to write audit log", "error", err, "event", audit.BillingTokensForfeitedEvent, "customer_id", c.ID)
+			}
+		}
 		if err := d.creditService.DeleteByAccountID(ctx, c.ID); err != nil {
 			return fmt.Errorf("failed to delete org while deleting a billing account transactions[%s]: %w", c.ID, err)
 		}
@@ -412,23 +455,162 @@ func (d Service) DeleteUser(ctx context.Context, userID string) error {
 	return d.userService.Delete(ctx, userID)
 }
 
-func (d Service) canDelete(ctx context.Context, id string) error {
-	// check if any invoice is present for customer
+// ensureDeletable collects everything that blocks deleting the organization and
+// returns it all as one BlockedError, so the caller gets a full checklist
+// instead of discovering blockers one retry at a time.
+//
+// A running subscription on a paid plan blocks the delete: the caller has
+// to downgrade it to the standard (default) plan first. A subscription on
+// the standard plan is not a blocker — once no blockers are left,
+// ensureDeletable cancels it itself, before any deletion starts. The cancel
+// is immediate and bills unbilled usage on the spot, so the invoice check
+// runs once more after it: a final invoice created by the cancel still
+// blocks the delete until it is paid.
+//
+// Unused tokens do not block either: the delete forfeits them. The client
+// gets the caller's confirmation before sending the delete, and the
+// forfeited amount is written to an audit record during teardown.
+//
+// Accounts without a billing provider are only checked for token balances:
+// their subscription and invoice rows have nothing behind them the caller
+// could cancel or pay.
+func (d Service) ensureDeletable(ctx context.Context, id string) error {
 	customers, err := d.customerService.List(ctx, customer.Filter{
 		OrgID: id,
 	})
 	if err != nil {
 		return err
 	}
 
+	// resolve the one plan a running subscription may still be on; any other
+	// active plan must be downgraded by the caller first
+	standardPlanID, err := d.standardPlanID(ctx, customers)
+	if err != nil {
+		return err
+	}
+
+	var blockers []Blocker
+	for _, c := range customers {
+		if !c.IsOffline() {
+			subs, err := d.subService.List(ctx, subscription.Filter{CustomerID: c.ID})
+			if err != nil {
+				return fmt.Errorf("failed to check subscriptions for billing account[%s]: %w", c.ID, err)
+			}
+			for _, sub := range subs {
+				if sub.IsActive() && sub.PlanID != standardPlanID {
+					blockers = append(blockers, Blocker{
+						Type:    BlockerActiveSubscription,
+						Subject: sub.ID,
+						Message: fmt.Sprintf("subscription[%s] is %s on a paid plan: downgrade to the standard plan, then retry the delete", sub.ID, sub.State),
+					})
+				}
+			}
+
+			bs, err := d.invoiceBlockers(ctx, c)
+			if err != nil {
+				return err
+			}
+			blockers = append(blockers, bs...)
+		}
+
+		balance, err := d.creditService.GetBalance(ctx, c.ID)
+		if err != nil {
+			return fmt.Errorf("failed to check token balance of billing account[%s]: %w", c.ID, err)
+		}
+		// the balance goes below zero when the account has an overdraft
+		// floor (credit_min under zero, the postpaid setup) and tokens were
+		// spent on credit. That debt is money owed, so it must be settled
+		// before the org can go
+		if balance < 0 {
+			blockers = append(blockers, Blocker{
+				Type:    BlockerNegativeTokenBalance,
+				Subject: c.ID,
+				Message: fmt.Sprintf("billing account[%s] owes %d tokens: contact support to settle the balance, then retry the delete", c.ID, -balance),
+			})
+		}
+	}
+	if len(blockers) > 0 {
+		return &BlockedError{OrgID: id, Blockers: blockers}
+	}
+
+	// no blockers were found, so the delete will happen. The only
+	// subscriptions still running are on the standard plan: cancel them,
+	// then check the invoices again because the cancel may have created a
+	// final one. This runs only after every blocker is clear, so a blocked
+	// delete never costs the caller their subscription
 	for _, c := range customers {
-		if invoices, err := d.invoiceService.List(ctx, invoice.Filter{CustomerID: c.ID}); err != nil {
-			return fmt.Errorf("failed to check invoices for billing account[%s]: %w", c.ID, err)
-		} else if len(invoices) > 0 {
-			if DisableDeleteIfBilled {
-				return fmt.Errorf("cannot delete organization with billing account[%s]", c.ID)
+		if c.IsOffline() {
+			continue
+		}
+		subs, err := d.subService.List(ctx, subscription.Filter{CustomerID: c.ID})
+		if err != nil {
+			return fmt.Errorf("failed to check subscriptions for billing account[%s]: %w", c.ID, err)
+		}
+		canceled := false
+		for _, sub := range subs {
+			if !sub.IsActive() {
+				continue
+			}
+			if _, err := d.subService.Cancel(ctx, sub.ID, true); err != nil {
+				return fmt.Errorf("failed to cancel subscription[%s] of billing account[%s]: %w", sub.ID, c.ID, err)
 			}
+			canceled = true
 		}
+		if canceled {
+			bs, err := d.invoiceBlockers(ctx, c)
+			if err != nil {
+				return err
+			}
+			blockers = append(blockers, bs...)
+		}
+	}
+	if len(blockers) > 0 {
+		return &BlockedError{OrgID: id, Blockers: blockers}
 	}
 	return nil
 }
+
+// standardPlanID resolves the configured default plan to its id. Without a
+// configured default plan every active subscription blocks the delete. The
+// lookup is skipped when no billing account talks to a provider.
+func (d Service) standardPlanID(ctx context.Context, customers []customer.Customer) (string, error) {
+	if d.defaultPlan == "" {
+		return "", nil
+	}
+	if !slices.ContainsFunc(customers, func(c customer.Customer) bool { return !c.IsOffline() }) {
+		return "", nil
+	}
+	standardPlan, err := d.planService.GetByID(ctx, d.defaultPlan)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve the default plan[%s]: %w", d.defaultPlan, err)
+	}
+	return standardPlan.ID, nil
+}
+
+// invoiceBlockers returns a blocker for every invoice of the account the
+// caller can still pay; paid, void, and draft invoices don't block. The
+// billing provider keeps its own permanent copy of every invoice, so
+// deleting our rows later loses nothing.
+func (d Service) invoiceBlockers(ctx context.Context, c customer.Customer) ([]Blocker, error) {
+	// the local invoice rows sync from the provider on a timer, so pull
+	// them fresh first: a just-paid invoice must not block, a just-created
+	// one must
+	if err := d.invoiceService.SyncWithProvider(ctx, c); err != nil {
+		return nil, fmt.Errorf("failed to sync invoices for billing account[%s]: %w", c.ID, err)
+	}
+	invoices, err := d.invoiceService.List(ctx, invoice.Filter{CustomerID: c.ID, NonZeroOnly: true})
+	if err != nil {
+		return nil, fmt.Errorf("failed to check invoices for billing account[%s]: %w", c.ID, err)
+	}
+	var blockers []Blocker
+	for _, inv := range invoices {
+		if inv.State == invoice.OpenState || inv.State == invoice.UncollectibleState {
+			blockers = append(blockers, Blocker{
+				Type:    BlockerUnpaidInvoice,
+				Subject: inv.ID,
+				Message: fmt.Sprintf("invoice[%s] is unpaid: pay it via its hosted payment page, then retry the delete", inv.ID),
+			})
+		}
+	}
+	return blockers, nil
+}