feat: implement global subscription management with multi-currency, group plans, and referral rewards

[yours-anjikon]

Summary

This PR introduces three major subscription platform capabilities that significantly expand SubTrackr's global billing and subscription management experience.

Closes #540

Closes #541

Closes #542

---

Overview

This contribution introduces three large platform features:

• Multi-currency subscription billing
• Group / Family subscription plans
• Referral & affiliate commission system

Together these additions enable merchants to operate globally while improving subscription sharing, billing flexibility, and customer acquisition.

---

Issue #540 — Multi-Currency Subscription Support

Background

Subscriptions currently operate exclusively in USD, limiting international adoption and forcing users to manually account for exchange-rate differences.

Solution

Implemented comprehensive multi-currency billing support.

Features

• Merchant currency configuration

• Support for 20+ fiat currencies

• Real-time FX conversion using configurable Oracle providers

• Automatic conversion during:

  • Subscription creation
  • Renewal cycles
  • Merchant settlement

• FX cache with configurable expiration (default 5 minutes)

• Multi-currency invoice generation displaying:

  • Original currency
  • Converted settlement currency

• Merchant payout conversion into preferred settlement currency

Edge Cases

Implemented handling for:

• FX provider unavailable
• Cached fallback rates
• Zero-value subscriptions
• Currency precision differences
• Exchange-rate refresh failures

Technical Changes

• Currency Oracle integration
• Extended Currency enum
• FX Conversion Service
• Currency formatting utilities
• Stellar price feed consumer contract

Tests

Added:

• FX conversion tests
• Cache expiration tests
• Fallback provider tests
• Invoice generation tests

---

Issue #541 — Group & Family Subscription Management

Background

Subscriptions were previously limited to individual ownership with no shared billing model.

Solution

Implemented shared subscription management for families and teams.

Features

Group owners can:

• Create shared subscription groups
• Configure maximum seats
• Invite members
• Manage member roles
• Remove members
• Monitor shared usage
• View centralized billing

Members can:

• Accept invitations
• Decline invitations
• Join shared subscriptions
• Consume allocated seats
• View personal usage

Seat Models

Supports:

• Fixed seat allocation
• Shared usage pooling

Billing

Implemented:

• Mid-cycle prorated billing
• Automatic seat reassignment
• Shared usage accounting

Edge Cases

Handled:

• Seat reduction during plan downgrade
• Owner cancellation
• Orphaned groups
• Member removal
• Access revocation

Technical Changes

• Group Membership Ledger contract
• Group domain module
• Service & controller layer
• Zustand group store
• Invite email templates
• GroupManagementScreen
• MemberListScreen

Tests

Added:

• Group lifecycle tests
• Invitation flow tests
• Seat allocation tests
• Billing adjustment tests

---

Issue #542 — Referral & Affiliate Platform

Background

Merchants currently have no built-in referral or affiliate infrastructure.

Solution

Added a complete referral management platform.

Referral Features

• Referral code generation
• UTM campaign builder
• Cookie attribution
• Link attribution
• Direct referral attribution

Commission Models

Supports:

• Flat reward
• Percentage commission
• Recurring commission
• Multi-tier (Level 1–3)

Dashboard

Added Affiliate Dashboard showing:

• Clicks
• Conversions
• Revenue
• Pending payouts
• Completed payouts
• Conversion funnel
• Commission history

Automated Payouts

Implemented:

• Stellar USDC payout automation
• Threshold-based payouts
• Scheduled payout jobs

Fraud Protection

Added detection for:

• Self referrals
• Duplicate device
• Duplicate IP
• Referral abuse

Edge Cases

Implemented handling for:

• Subscription upgrades
• Downgrades
• Refund clawbacks
• Commission reversals

Technical Changes

• Referral domain module
• Commission Vault Soroban contract
• ReferralScreen
• AffiliateDashboardScreen
• Conversion tracking service
• Commission payout scheduler

Tests

Added:

• Attribution tests
• Commission calculation tests
• Fraud detection tests
• Payout automation tests

---

Files Updated

backend/
├── currency/
├── groups/
├── referrals/

contracts/
├── currency-oracle/
├── group-ledger/
└── commission-vault/

mobile/
├── GroupManagementScreen
├── MemberListScreen
├── ReferralScreen
└── AffiliateDashboardScreen

src/store/
└── groupStore.ts

emails/
└── group-invite-template

---

Validation

Backend

npm run lint
npm run test
npm run build

Contracts

cargo fmt --check
cargo clippy
cargo test

Mobile

npm run typecheck

Integration

• FX conversion
• Group invitations
• Shared billing
• Referral attribution
• Commission payouts
• Fraud detection
• Dashboard analytics

All validation completed successfully.

---

Impact

This PR significantly expands SubTrackr's subscription capabilities by introducing:

• Global multi-currency billing
• Enterprise-ready family and team subscriptions
• Referral and affiliate monetization
• Automated Stellar commission payouts
• Shared billing management
• Improved merchant analytics
• Stronger fraud protection
• Better international user experience

These features are fully integrated into the existing subscription architecture while maintaining backward compatibility with existing subscription plans.

[drips-wave]

@yours-anjikon Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits