Saavo

联盟

推荐链接、佣金和月度结算。根据产品需求调整佣金策略后即可使用，打款仍由管理员审核。

Saavo 模板内置了完整的联盟推广系统，涵盖推荐链接生成、注册归因、基于套餐的佣金计算、用户端佣金总览以及后台月度结算等核心功能。

在开发自有产品时，通常无需从零搭建返佣系统。您只需开启联盟推广开关，并按真实套餐配置相应的佣金比例，系统即可在用户支付成功后自动完成记账。

需要特别说明的是，该模板仅负责佣金数据的记录与展示，实际的打款环节（如连接 PayPal 或银行账户）仍需人工操作。系统不会替代人工审核，也不会自动执行资金结算。

已有功能

模板初始化后，以下功能开箱即用：

能力默认入口默认状态
推广介绍页/affiliate始终可访问
推荐链接/ref/:code联盟开启时注册
用户联盟中心/account/affiliate需登录，且联盟开启
联盟用户/dashboard/affiliates/users管理员可访问
月度结算/dashboard/affiliates/payouts管理员审核打款

系统通过 HttpOnly Cookie（saavo_affiliate_referral）来记录推荐码，并遵循“首次触达优先”的原则。当匿名访客首次通过有效的推荐链接访问时，系统会保存该推荐码，后续即便再次点击其他推广链接，原有的归因关系也不会被覆盖。

当新用户完成注册后，系统会自动将其归属到对应的推广者名下；同时，已登录用户点击推荐链接，也不会改写其原有的归因关系。在推广者的准入与资金安全方面，系统设定了严格的门槛。用户必须完成登录及邮箱验证后，方可进入联盟中心并启用推广身份。由于收款资料属于敏感信息，只有满足条件的推广者才能访问该模块，且在读取或保存收款信息时，还必须通过 Step-up（升级）验证以确保安全。

关于佣金的结算与配置，系统会在支付 Webhook 处理成功后自动写入佣金数据。在配置佣金策略时，必须严格指向 config/products.ts 文件中已存在的产品 ID 和套餐 ID，若指向未配置的套餐，系统将无法产生并记录佣金。

用户联盟中心

先体验联盟推广流程

修改佣金比例之前，建议先看懂默认链路。

推广者在账号中心开启联盟
↓
得到 8 位推荐码，链接为 /ref/{code}
↓
访客打开推荐链接，写入推荐 Cookie
↓
访客注册
↓
该用户后续购买配置了佣金的套餐
↓
支付成功后写入佣金记录
↓
管理员在月结页刷新、审核并记录打款

默认策略只给示例套餐 saavo_starter.license 产品结算佣金，佣金比例设定为净额的 20%。

在当前的默认配置下，结算次数被限制为 1 次，这意味着系统不会根据账单周期进行重复计算，佣金仅会结算一次。对于一次性购买的产品而言，该周期配置本身并不适用，系统会默认只结算一笔佣金。

提示

20% 和 license 套餐都是示例。正式对外前必须改成自己的产品和真实佣金，否则会按模板比例记账。

配置联盟推广

联盟总开关和佣金策略都在 config/affiliate.ts 文件中进行配置。

开启或关闭联盟推广

默认已启用：

enabled: true,

不需要联盟时设为 false。关闭后：

  • /ref/:code 不再注册
  • /account/affiliate 返回 404
  • 账号导航不再出现联盟项
  • 用户侧联盟 API 返回 404

后台管理员主动关闭联盟功能后，联盟计划页面 /affiliate 仍然可以访问，但会提示该功能当前不可用。管理后台中的联盟模块不会被移除，管理员仍然可以查看已有的推广者、佣金等历史数据

按套餐设置佣金

plans 必须对应产品目录里的 ID，没有设置的产品不会生成佣金。

百分比示例：

saavo_starter: {
    license: {
        commission: {
            type: 'percentage',
            basisPoints: 2000,
            base: 'net_subtotal',
        },
        subscriptionPaymentLimit: 1,
    },
},

其中：

  • basisPoints: 100 为 1%，2000 为 20%。
  • base: 'subtotal' 表示按折扣前、税前的小计计算；base: 'net_subtotal' 表示按折扣后、税前的小计计算；base: 'total' 表示按最终含税金额计算。
  • subscriptionPaymentLimit: 1 表示按成功扣款次数计算，不是按自然月。1 表示只计首笔。

也可以改成固定金额。每个套餐同时只能启用一种佣金形态。修改政策不会改写已经落库的佣金快照。月结刷新时，订阅次数上限会按当前配置重新计算。

设置结算规则

同一文件还控制结算周期和提现方式：

payoutInterval: '1 month',
payout: {
    methods: ['paypal', 'wise', 'wechat'],
    minimumAmountMinor: 2000,
    currency: 'usd',
},

minimumAmountMinor 使用货币最小单位，2000 配 usd 表示 20.00 美元。管理员在后台刷新月结、审核后，再自行向推广者打款，并保存支付记录。

在业务中使用联盟推广

对大多数产品，联盟不需要额外业务代码。支付成功后，模板会按 Price ID 匹配套餐并记账。但仍需确保以下几点：

  • 产品目录里的套餐 ID 与联盟策略一致
  • 需要计佣的套餐都写进 affiliate.plans
  • 推广入口指向用户自己的 /ref/{code}

不要在 Checkout 成功页自己插入佣金行，也不要再做一套 user_credits 式的平行返佣账本。

如果产品有自己的落地页，也可以继续使用现有推荐 Cookie 捕获逻辑，而不要再发明第二个归因 Cookie。

上线检查

联盟涉及真实分成，上线前建议至少确认：

  • 佣金策略已不是示例中的 20%，并且对应真实的 product/plan ID。
  • 未配置佣金的套餐购买后确实不会产生佣金。
  • /ref/{code} 能写入推荐 Cookie，新用户注册后能归因到推广者。
  • 用测试卡完成一次计佣套餐购买后，后台能看到佣金记录。
  • 推广者可以在 /account/affiliate 查看佣金并填写收款方式。
  • 未验证邮箱不能启用联盟，修改收款资料时会要求 step-up 验证。
  • 管理员可以刷新月结、审核并记录打款。
  • 如不需要联盟，enabled 已设为 false，账号入口已消失。

建议用两个账号测试：一个作为推广者，一个作为被推荐并完成购买的新用户。

常见问题

接下来

根据接下来要开发的功能，可以继续阅读：

大多数产品走完本章后，只需要改开关和佣金策略。

打款、税务和合同仍由你自己的运营流程完成。