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

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
+}