Sub2API Payment System Load Balancing Strategies: Round Robin and Least Daily Amount

Sub2API supports two payment load balancing strategies: Round Robin, which rotates requests evenly across providers, and Least Daily Amount, which routes traffic to the provider with the lowest daily spend.

The Wei-Shaw/sub2api repository implements configurable payment provider selection to optimize transaction routing. Understanding the available load balancing strategies in the Sub2API payment system is essential for administrators managing multiple payment gateways. This guide examines the source code implementation of both strategies, their configuration interfaces, and persistence mechanisms.

Available Load Balancing Strategies

Sub2API supports two distinct algorithms for distributing payment requests across configured providers. Both strategies are defined in the frontend internationalization files and handled as string constants in the backend.

Round Robin (Default)

The Round Robin strategy cycles through payment providers in sequential order, ensuring equal request distribution regardless of transaction value. When no explicit strategy is configured, the system defaults to "round-robin" as implemented in the settings handler.

Least Daily Amount

The Least Daily Amount strategy routes each payment to the provider with the smallest cumulative transaction total for the current day. This algorithm prevents any single gateway from accumulating disproportionate daily volume and is identified by the string "least_amount" in system configurations.

Implementation in the Source Code

The load balancing configuration flows through three distinct layers: the Vue.js administrative interface, Go backend DTOs, and persistent storage.

Frontend Configuration Interface

The administrative dashboard presents both strategies through a selection component bound to payment_load_balance_strategy in frontend/src/views/admin/SettingsView.vue. The interface labels are defined in frontend/src/i18n/locales/en/admin/settings.ts with keys strategyRoundRobin and strategyLeastAmount.

Backend Data Structures

The backend accepts strategy updates through the SettingsUpdateDTO struct in backend/internal/handler/admin/setting_handler_update.go:

type SettingsUpdateDTO struct {
    // ... other fields ...
    PaymentLoadBalanceStrat *string `json:"payment_load_balance_strategy"`
}

The system returns current settings via SettingsDTO defined in backend/internal/handler/dto/settings.go:

type SettingsDTO struct {
    // ... other fields ...
    PaymentLoadBalanceStrat string `json:"payment_load_balance_strategy"`
}

Configuring Payment Load Balancing

Administrators can modify the active strategy through either the REST API or the administrative web interface.

To update the strategy via the API endpoint POST /admin/settings, submit the following JSON payload:

{
  "payment_load_balance_strategy": "least_amount"
}

When implementing client-side logic in the Vue frontend, reference the strategy from the form model:

// frontend/src/views/admin/SettingsView.vue
await this.$api.admin.settings.update({
  payment_load_balance_strategy: this.form.payment_load_balance_strategy,
});

To retrieve the current strategy in backend services, access the configuration field:

func (s *SettingsService) GetPaymentLoadBalanceStrategy() string {
    return s.cfg.PaymentLoadBalanceStrat
}

Summary

• Sub2API provides Round Robin and Least Daily Amount strategies for payment provider selection.
• Round Robin is the default fallback when no strategy is explicitly configured.
• Configuration persists through the payment_load_balance_strategy field in SettingsUpdateDTO and SettingsDTO.
• The frontend interface in SettingsView.vue exposes both options with localized labels.
• Valid strategy values are "round-robin" and "least_amount".

Frequently Asked Questions

What is the default load balancing strategy in Sub2API?

The system defaults to Round Robin when the payment_load_balance_strategy field is empty or unset. This fallback logic is implemented in the frontend configuration handler within frontend/src/views/admin/SettingsView.vue.

How does the Least Daily Amount strategy work?

This strategy calculates the cumulative transaction volume for each payment provider during the current day and routes new requests to the provider with the lowest total. It effectively balances daily spend across multiple gateways rather than request count.

Where is the payment load balance strategy stored in the codebase?

The strategy identifier is stored as a string field within the settings DTOs. The update structure resides in backend/internal/handler/admin/setting_handler_update.go while the response structure is defined in backend/internal/handler/dto/settings.go. Both use the JSON key payment_load_balance_strategy.

Can I change the load balancing strategy via API?

Yes. Submit a POST request to the /admin/settings endpoint with a JSON body containing "payment_load_balance_strategy": "round-robin" or "least_amount". The backend validates and persists this value through the SettingsUpdateDTO structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}