feat: Add self serve billing management UI

admin/billing.go

@@ -210,6 +210,9 @@ func (s *Service) StartTrial(ctx context.Context, org *database.Organization) (*
 	sub, err := s.Biller.GetActiveSubscription(ctx, org.BillingCustomerID)
 	if err != nil {
 		if !errors.Is(err, billing.ErrNotFound) {
+			if errors.Is(err, billing.ErrCustomerIDRequired) {
+				return nil, nil, fmt.Errorf("org billing not initialized yet, retry")
+			}
 			return nil, nil, fmt.Errorf("failed to get subscriptions for customer: %w", err)
 		}
 	}

admin/billing/orb.go

@@ -28,6 +28,8 @@ const (
 	avalaraTaxExemptionCode = "R" // code for NON-RESIDENT
 )
 
+var ErrCustomerIDRequired = errors.New("customer id is required")
+
 var _ Biller = &Orb{}
 
 type Orb struct {
@@ -202,7 +204,7 @@ func (o *Orb) GetActiveSubscription(ctx context.Context, customerID string) (*Su
 	}
 
 	if len(subs) > 1 {
-		return nil, fmt.Errorf("multiple active subscriptions found for customer %s", customerID)
+		return nil, fmt.Errorf("multiple active subscriptions (%d) found for customer %s", len(subs), customerID)
 	}
 
 	return subs[0], nil
@@ -445,6 +447,10 @@ func (o *Orb) createSubscription(ctx context.Context, customerID string, plan *P
 }
 
 func (o *Orb) getSubscriptions(ctx context.Context, customerID string, status orb.SubscriptionListParamsStatus) ([]*Subscription, error) {
+	if customerID == "" { // weird behaviour but empty external customer id returns all active subscriptions
+		return nil, ErrCustomerIDRequired
+	}
+
 	sub, err := o.client.Subscriptions.List(ctx, orb.SubscriptionListParams{
 		ExternalCustomerID: orb.String(customerID),
 		Status:             orb.F(status),

admin/database/postgres/migrations/0052.sql

@@ -0,0 +1 @@
+ALTER TABLE assets ALTER COLUMN org_id DROP NOT NULL;

admin/jobs/river/biller_event_handlers.go

@@ -86,6 +86,7 @@ func (w *PaymentFailedWorker) Work(ctx context.Context, job *river.Job[PaymentFa
 		OrgName:            org.Name,
 		Currency:           job.Args.Currency,
 		Amount:             job.Args.Amount,
+		PaymentURL:         w.admin.URLs.PaymentPortal(org.Name),
 		GracePeriodEndDate: gracePeriodEndDate,
 	})
 	if err != nil {
@@ -242,9 +243,10 @@ func (w *PaymentFailedGracePeriodCheckWorker) paymentFailedGracePeriodCheck(ctx
 
 		// send email
 		err = w.admin.Email.SendInvoiceUnpaid(&email.InvoiceUnpaid{
-			ToEmail: org.BillingEmail,
-			ToName:  org.Name,
-			OrgName: org.Name,
+			ToEmail:    org.BillingEmail,
+			ToName:     org.Name,
+			OrgName:    org.Name,
+			PaymentURL: w.admin.URLs.PaymentPortal(org.Name),
 		})
 		if err != nil {
 			return fmt.Errorf("failed to send project hibernated due to payment overdue email for org %q: %w", org.Name, err)

admin/jobs/river/org_jobs.go

@@ -111,7 +111,7 @@ func (w *StartTrialWorker) Work(ctx context.Context, job *river.Job[StartTrialAr
 
 	org, sub, err := w.admin.StartTrial(ctx, org)
 	if err != nil {
-		w.logger.Error("failed to start trial for organization", zap.String("org_name", org.Name), zap.String("org_id", org.ID), zap.Error(err))
+		w.logger.Error("failed to start trial for organization", zap.String("org_id", job.Args.OrgID), zap.Error(err))
 		return err
 	}
 

admin/jobs/river/river.go

@@ -343,6 +343,7 @@ func (c *Client) StartOrgTrial(ctx context.Context, orgID string) (*jobs.InsertR
 		UniqueOpts: river.UniqueOpts{
 			ByArgs: true,
 		},
+		MaxAttempts: 5, // override default retries as init org billing job should complete before this if org creation and project deployment were done in single flow
 	})
 	if err != nil {
 		return nil, err

admin/jobs/river/trial_checks.go

@@ -57,6 +57,7 @@ func (w *TrialEndingSoonWorker) trialEndingSoon(ctx context.Context) error {
 			ToEmail:      org.BillingEmail,
 			ToName:       org.Name,
 			OrgName:      org.Name,
+			UpgradeURL:   w.admin.URLs.UpgradePlan(org.Name),
 			TrialEndDate: m.EndDate,
 		})
 		if err != nil {
@@ -162,6 +163,7 @@ func (w *TrialEndCheckWorker) trialEndCheck(ctx context.Context) error {
 			ToEmail:            org.BillingEmail,
 			ToName:             org.Name,
 			OrgName:            org.Name,
+			UpgradeURL:         w.admin.URLs.UpgradePlan(org.Name),
 			GracePeriodEndDate: m.GracePeriodEndDate,
 		})
 		if err != nil {
@@ -284,9 +286,10 @@ func (w *TrialGracePeriodCheckWorker) trialGracePeriodCheck(ctx context.Context)
 
 		// send email
 		err = w.admin.Email.SendTrialGracePeriodEnded(&email.TrialGracePeriodEnded{
-			ToEmail: org.BillingEmail,
-			ToName:  org.Name,
-			OrgName: org.Name,
+			ToEmail:    org.BillingEmail,
+			ToName:     org.Name,
+			OrgName:    org.Name,
+			UpgradeURL: w.admin.URLs.UpgradePlan(org.Name),
 		})
 		if err != nil {
 			return fmt.Errorf("failed to send trial grace period ended email for org %q: %w", org.Name, err)

admin/server/billing.go

@@ -207,6 +207,10 @@ func (s *Server) CancelBillingSubscription(ctx context.Context, req *adminv1.Can
 		return nil, status.Error(codes.PermissionDenied, "not allowed to cancel org subscription")
 	}
 
+	if org.BillingCustomerID == "" {
+		return nil, status.Error(codes.FailedPrecondition, "billing not yet initialized for the organization")
+	}
+
 	endDate, err := s.admin.Biller.CancelSubscriptionsForCustomer(ctx, org.BillingCustomerID, billing.SubscriptionCancellationOptionEndOfSubscriptionTerm)
 	if err != nil {
 		return nil, status.Error(codes.Internal, err.Error())
@@ -233,6 +237,16 @@ func (s *Server) CancelBillingSubscription(ctx context.Context, req *adminv1.Can
 		return nil, status.Error(codes.Internal, err.Error())
 	}
 
+	err = s.admin.Email.SendSubscriptionCancelled(&email.SubscriptionCancelled{
+		ToEmail: org.BillingEmail,
+		ToName:  org.Name,
+		OrgName: org.Name,
+		EndDate: endDate,
+	})
+	if err != nil {
+		return nil, status.Error(codes.Internal, err.Error())
+	}
+
 	s.logger.Named("billing").Warn("subscription cancelled", zap.String("org_id", org.ID), zap.String("org_name", org.Name))
 
 	return &adminv1.CancelBillingSubscriptionResponse{}, nil
@@ -366,6 +380,11 @@ func (s *Server) GetPaymentsPortalURL(ctx context.Context, req *adminv1.GetPayme
 		return nil, status.Error(codes.FailedPrecondition, "payment customer not initialized yet for the organization")
 	}
 
+	// returnUrl is mandatory so if not passed default to home page
+	if req.ReturnUrl == "" {
+		req.ReturnUrl = s.admin.URLs.Frontend()
+	}
+
 	url, err := s.admin.PaymentProvider.GetBillingPortalURL(ctx, org.PaymentCustomerID, req.ReturnUrl)
 	if err != nil {
 		return nil, status.Error(codes.Internal, err.Error())
@@ -784,11 +803,11 @@ func subscriptionToDTO(sub *billing.Subscription) *adminv1.Subscription {
 	return &adminv1.Subscription{
 		Id:                           sub.ID,
 		Plan:                         billingPlanToDTO(sub.Plan),
-		StartDate:                    timestamppb.New(sub.StartDate),
-		EndDate:                      timestamppb.New(sub.EndDate),
-		CurrentBillingCycleStartDate: timestamppb.New(sub.CurrentBillingCycleStartDate),
-		CurrentBillingCycleEndDate:   timestamppb.New(sub.CurrentBillingCycleEndDate),
-		TrialEndDate:                 timestamppb.New(sub.TrialEndDate),
+		StartDate:                    valOrNullTime(sub.StartDate),
+		EndDate:                      valOrNullTime(sub.EndDate),
+		CurrentBillingCycleStartDate: valOrNullTime(sub.CurrentBillingCycleStartDate),
+		CurrentBillingCycleEndDate:   valOrNullTime(sub.CurrentBillingCycleEndDate),
+		TrialEndDate:                 valOrNullTime(sub.TrialEndDate),
 	}
 }
 
@@ -871,17 +890,17 @@ func billingIssueMetadataToDTO(t database.BillingIssueType, m database.BillingIs
 		return &adminv1.BillingIssueMetadata{
 			Metadata: &adminv1.BillingIssueMetadata_OnTrial{
 				OnTrial: &adminv1.BillingIssueMetadataOnTrial{
-					EndDate:            timestamppb.New(m.(*database.BillingIssueMetadataOnTrial).EndDate),
-					GracePeriodEndDate: timestamppb.New(m.(*database.BillingIssueMetadataOnTrial).GracePeriodEndDate),
+					EndDate:            valOrNullTime(m.(*database.BillingIssueMetadataOnTrial).EndDate),
+					GracePeriodEndDate: valOrNullTime(m.(*database.BillingIssueMetadataOnTrial).GracePeriodEndDate),
 				},
 			},
 		}
 	case database.BillingIssueTypeTrialEnded:
 		return &adminv1.BillingIssueMetadata{
 			Metadata: &adminv1.BillingIssueMetadata_TrialEnded{
 				TrialEnded: &adminv1.BillingIssueMetadataTrialEnded{
-					EndDate:            timestamppb.New(m.(*database.BillingIssueMetadataTrialEnded).EndDate),
-					GracePeriodEndDate: timestamppb.New(m.(*database.BillingIssueMetadataTrialEnded).GracePeriodEndDate),
+					EndDate:            valOrNullTime(m.(*database.BillingIssueMetadataTrialEnded).EndDate),
+					GracePeriodEndDate: valOrNullTime(m.(*database.BillingIssueMetadataTrialEnded).GracePeriodEndDate),
 				},
 			},
 		}
@@ -902,12 +921,13 @@ func billingIssueMetadataToDTO(t database.BillingIssueType, m database.BillingIs
 		invoices := make([]*adminv1.BillingIssueMetadataPaymentFailedMeta, 0)
 		for k := range paymentFailed.Invoices {
 			invoices = append(invoices, &adminv1.BillingIssueMetadataPaymentFailedMeta{
-				InvoiceId:     paymentFailed.Invoices[k].ID,
-				InvoiceNumber: paymentFailed.Invoices[k].Number,
-				InvoiceUrl:    paymentFailed.Invoices[k].URL,
-				AmountDue:     paymentFailed.Invoices[k].Amount,
-				Currency:      paymentFailed.Invoices[k].Currency,
-				DueDate:       timestamppb.New(paymentFailed.Invoices[k].DueDate),
+				InvoiceId:          paymentFailed.Invoices[k].ID,
+				InvoiceNumber:      paymentFailed.Invoices[k].Number,
+				InvoiceUrl:         paymentFailed.Invoices[k].URL,
+				AmountDue:          paymentFailed.Invoices[k].Amount,
+				Currency:           paymentFailed.Invoices[k].Currency,
+				DueDate:            valOrNullTime(paymentFailed.Invoices[k].DueDate),
+				GracePeriodEndDate: valOrNullTime(paymentFailed.Invoices[k].GracePeriodEndDate),
 			})
 		}
 		return &adminv1.BillingIssueMetadata{
@@ -921,7 +941,7 @@ func billingIssueMetadataToDTO(t database.BillingIssueType, m database.BillingIs
 		return &adminv1.BillingIssueMetadata{
 			Metadata: &adminv1.BillingIssueMetadata_SubscriptionCancelled{
 				SubscriptionCancelled: &adminv1.BillingIssueMetadataSubscriptionCancelled{
-					EndDate: timestamppb.New(m.(*database.BillingIssueMetadataSubscriptionCancelled).EndDate),
+					EndDate: valOrNullTime(m.(*database.BillingIssueMetadataSubscriptionCancelled).EndDate),
 				},
 			},
 		}
@@ -973,6 +993,13 @@ func comparableInt64(v *int64) int64 {
 	return *v
 }
 
+func valOrNullTime(v time.Time) *timestamppb.Timestamp {
+	if v.IsZero() {
+		return nil
+	}
+	return timestamppb.New(v)
+}
+
 func biggerOfInt(ptr *int, def int) int {
 	if ptr == nil {
 		return def

admin/urls.go

@@ -336,3 +336,14 @@ func (u *URLs) AlertOpen(org, project, alert string) string {
 func (u *URLs) AlertEdit(org, project, alert string) string {
 	return urlutil.MustJoinURL(u.Frontend(), org, project, "-", "alerts", alert)
 }
+
+// UpgradePlan returns the landing page URL to either upgrade to plan or redirect to payment portal if there are any issues.
+func (u *URLs) UpgradePlan(org string) string {
+	return urlutil.MustWithQuery(urlutil.MustJoinURL(u.Frontend(), org, "-", "settings", "billing"), map[string]string{"upgrade": "true"})
+}
+
+// PaymentPortal returns the landing page url that redirects user to payment portal
+// Since the payment link can expire it is generated in this landing page on demand.
+func (u *URLs) PaymentPortal(org string) string {
+	return urlutil.MustJoinURL(u.Frontend(), org, "-", "settings", "billing", "payment")
+}

admin/user.go

@@ -246,6 +246,19 @@ func (s *Service) CreateOrganizationForUser(ctx context.Context, userID, email,
 
 	s.Logger.Info("created org", zap.String("name", orgName), zap.String("user_id", userID))
 
+	// raise never subscribed billing issue in sync to prevent race condition where first project is deployed before issue is raised and thus start trial job not submitted
+	if s.Biller.Name() != "noop" {
+		_, err := s.DB.UpsertBillingIssue(ctx, &database.UpsertBillingIssueOptions{
+			OrgID:     org.ID,
+			Type:      database.BillingIssueTypeNeverSubscribed,
+			Metadata:  database.BillingIssueMetadataNeverSubscribed{},
+			EventTime: org.CreatedOn,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to upsert billing error: %w", err)
+		}
+	}
+
 	// Submit job to init org billing // TODO modify river client to allow job submission as part of transaction
 	_, err = s.Jobs.InitOrgBilling(ctx, org.ID)
 	if err != nil {