TinyShip 2.5.0 Released
This release adds a complete Affiliate Commission System to TinyShip. Users can invite new users through dedicated referral links, automatically earn cash commissions from each successful payment made by referred users, and complete the full withdrawal request and admin approval flow.
The system is integrated across all six payment providers: Stripe, PayPal, Creem, WeChat Pay, Alipay, and DodoPayments. It is adapted across all three frameworks and supports both PostgreSQL and SQLite.
Core Additions
Referral Links and Automatic Attribution: Users get a dedicated referral link from the Dashboard, such as https://yourapp.com?ref=aB3xK9mZ. When a referred user opens the link, the referral code is stored in a cookie for 30 days. After signup, the first Dashboard visit binds the referral relationship
Signup Credit Bonus: When the referred user completes signup binding, both the referrer and referred user receive configurable credit rewards, defaulting to 10 credits each. Rewards are issued through creditService.addCredits and added to user credit balances
Cash Commission on Purchases: Every successful payment from a referred user, including subscriptions, one-time payments, and credit purchases, can trigger commission calculation. The system supports percentage commission, defaulting to 20%, and fixed-amount commission. Commission is added to the referrer's commissionBalance and can be withdrawn. All six payment providers are covered
Withdrawal Management: Users submit withdrawal requests from the Dashboard. The system deducts balance immediately to prevent over-withdrawal. Admins review requests in the admin panel, manually transfer funds after approval, and rejected requests automatically return the deducted balance
Admin Dashboard: Added Commissions and Withdrawals pages to the admin panel, with email search, pagination, commission record browsing, withdrawal request review, approve, and reject actions
Three-Layer Feature Toggle: The system is disabled by default. It only turns on after setting AFFILIATE_ENABLED=true. When disabled or unset, related UI tabs are hidden, APIs return disabled status, and payment Webhooks skip commission processing
Database Changes
Schema Extensions: Added referralCode, referredByCode, and commissionBalance to the users table. Added new commission and withdrawal tables, with Drizzle migrations synced for both PG and SQLite dialects
Configuration and Environment Variables
To avoid creating commission obligations before withdrawal and risk-control workflows are ready, explicitly set AFFILIATE_ENABLED=true before enabling the system. Other options can use their defaults:
AFFILIATE_COMMISSION_RATE— commission rate, default 20%AFFILIATE_FIXED_COMMISSION_AMOUNT— fixed commission amount, overriding percentage modeAFFILIATE_CURRENCY— settlement currency, default USDAFFILIATE_MIN_WITHDRAWAL— minimum withdrawal amount, default 100AFFILIATE_REFERRER_SIGNUP_BONUS/AFFILIATE_REFEREE_SIGNUP_BONUS— two-way signup credit rewards, default 10 eachAFFILIATE_COOKIE_EXPIRY_DAYS— referral cookie lifetime in days, default 30
i18n
Complete Bilingual Coverage: Dashboard tabs, commission stats, commission tables, withdrawal forms, admin pages, and error messages all use i18n keys with no hard-coded text
Testing and Stability
Full Lifecycle E2E Coverage: Added 33 E2E tests covering affiliate stats, referral link display, claim flow, Stripe / Dodo commission generation, withdrawal requests, admin commission views, and withdrawal approval
Three Frameworks × Two Databases Validation: All 6 combinations across Next.js / Nuxt / TanStack Start and PostgreSQL / SQLite passed
Documentation
User Guide: docs/user-guide/affiliate.md adds affiliate system configuration, including enablement, environment variables, workflows, admin operations, and FAQ
Implementation Docs: docs/implementation/affiliate-system.md documents architecture design, database schema, core modules, and framework adaptation details