技能介绍

问题场景

当 SaaS 用 Stripe 收款并引入推荐人或促销码时，难点不是挂上链接，而是把“谁带来的客户”稳定写入 Stripe Checkout / Subscription，再让佣金能正确匹配；同时还要处理 API base、文档站、签名密钥、测试模式、订阅元数据之间的坑。

技能如何工作

该技能先确认目标：上线推荐计划、修复归因、做集成、选套餐、调试，还是对比 PromoteKit 与 Tolt/Affonso。随后判断套餐是否开放 API 与 webhooks、结账方式是 Payment Link、自建后端 Checkout、API 订阅还是 Memberstack/Outseta/MemberSpace，以及使用推荐链接还是 Stripe promo code、是否已有真实资金流；非 PromoteKit 专属问题会路由到对应销售、漏斗或邮件技能。

在 PromoteKit 专属部分，它提供可执行的集成知识：API base 是 https://www.promotekit.com/api/v1，而 api.promotekit.com 返回的是仪表盘 HTML；文档应以 https://www.promotekit.com/docs 为准，docs. 子域是陈旧镜像。它说明自定义 Checkout 要从浏览器侧读取 window.promotekit_referral（PHP 为 $_COOKIE['promotekit_referral']），随订单发送并在 Stripe session 上设置 metadata.promotekit_referral；订阅还必须写入 subscription_data.metadata，否则循环佣金无法匹配。Webhook 需要使用 Svix 官方库做 raw-body 验证，express.raw 而非 express.json()，且 whsec_ 签名密钥不同于 API Key。它还要求写 POST /commissions 前先 GET 查重，因为该 API 没有幂等键。

边界与注意点

PromoteKit 只适配 Stripe billing，不支付推荐人，也不收集 W-9/W-8 或生成 1099；payouts API 只读，付款需导出 GET /commissions?payout_status=not_paid 后用 PayPal Mass Payments 或 Wise Batch Payments 完成。它只有 5 个创建侧 webhook，没有 commission.paid、封禁或流失事件，佣金与订阅状态需轮询。Stripe test mode 不会产生 referral，出现“没归因”时应先用小额 live charge 验证并退款。此处对套餐门槛和定价的归纳来自研究资料，可能已过时，请以 https://promotekit.com/pricing 为准。