跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
经常性收入，自动化管理。

客户订阅后，我们处理计费周期、续费重试和生命周期管理。你专注于产品即可。

​
工作原理

客户订阅 → 计费周期 → 自动扣款 → 循环
如果续费扣款未成功，订阅会进入 past_due 状态。这个状态表示订阅进入续费恢复阶段，而不是立即失效；系统会在宽限期内继续重试或等待用户更新支付方式。

​
订阅套餐如何建模

在 Waffo Pancake 中，每一个可单独购买的订阅选项 都是一个独立的订阅产品。 最常见的区分方式是计费周期，例如：
  • 月付
  • 年付
如果你同时提供月付和年付，通常应建模为 2 个订阅产品。
业务展示方式在 Waffo 中的建模方式
月付方案1 个订阅产品
年付方案1 个订阅产品

​
订阅状态

状态说明
pending等待首次付款
active正常运行，正常计费
trialing免费试用期
past_due续费扣款未成功，处于恢复/宽限阶段
canceling已请求取消，在当前周期结束前仍保持活跃
canceled当前周期结束后不再续费
expired订阅已过期
closed从未激活 — 支付超时

​
计费周期

周期频率最适用于
每周每 7 天高使用量产品
每月每月标准 SaaS
每季度每 3 个月B2B 软件
每年每 12 个月长期客户

​
免费试用

降低注册门槛，让客户先试用再购买。

​
配置试用

创建订阅产品时，在控制台中启用试用开关并设置试用天数。

​
平台级试用保护

Waffo Pancake 作为 Merchant of Record（MoR），会在平台层自动防止试用被重复滥用：
层级运作方式
平台层跨所有商户追踪消费者的试用历史，并为每次新订阅计算可用的最大试用天数。
商户侧可在通过 API 创建订单时传递 requested_trial_days，按客户缩短试用期或直接跳过试用。
两个层级如何交互：
  • 如果商户请求 ≤ 平台最大值 → 使用商户请求的值
  • 如果商户请求 > 平台最大值 → 回退到平台最大值
  • 如果商户未指定 → 使用完整的平台最大值

​
买家身份与试用保护

试用资格通过 buyerIdentity 追踪 — 您通过认证式结账提供的稳定标识符。平台使用此标识检测跨会话的重复试用领取。
不提供 buyerIdentity（匿名结账）时，试用资格检查将被完全跳过。买家可以通过更换邮箱地址无限领取试用。
7-14 天的试用效果最佳。太短 = 没有足够时间评估。太长 = 容易被遗忘。

​
续费恢复

当续费扣款未成功时，订阅会转为 past_due 状态。这个状态通常意味着系统正在等待支付方式更新，或处于重试与恢复窗口中，而不是立刻终止服务。 常见处理方式：
  • 系统通知客户更新支付方式
  • 在一定宽限期内保留访问权限
  • 后续按重试策略继续尝试扣款
past_due 更适合理解为“续费异常待恢复”，而不是“付款失败后立即终止”。

​
管理订阅

​
取消

取消时，订阅会先进入 canceling 中间状态，在当前计费周期结束时自动转为 canceled。客户在此期间保留访问权限。 
POST /v1/actions/subscription-order/cancel-order
{
  "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz"
}
响应中返回 canceling 状态，表示订阅将在当前周期结束后正式取消。
没有立即取消的选项。客户始终保留访问权限直到已付费周期结束。取消后状态流转为：active → canceling → canceled。

​
恢复订阅

如果订阅仍处于 canceling 状态，客户可以在当前周期结束前恢复订阅。 恢复后：
  • 订阅状态回到 active
  • 当前周期内的访问权限保持不变
  • 后续将按原有周期继续正常续费
恢复订阅适用于“已经请求取消，但尚未到期”的场景。本质上是撤销取消操作，而不是重新购买一个新订阅。

​
升级/降级

场景行为
周期中升级立即生效
周期中降级在当前计费周期结束时生效
POST /v1/actions/subscription-order/change-product
{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "targetProductId": "target-product-uuid"
}
此端点尚未实现（返回 501）。将在未来版本中提供。

​
指标

​
MRR（月经常性收入）

周订阅：    $10 × 4.33 = $43.30 MRR
月订阅：    $29 × 1 = $29 MRR
年订阅：    $290 ÷ 12 = $24.17 MRR

​
关键指标

指标含义
MRR月经常性收入
Churn取消订阅的百分比
LTV客户终身价值
ARPU每用户平均收入

​
Webhooks

通过 Webhook 订阅订阅生命周期事件。在 设置 → Webhook 中配置端点。
此处不列出具体的 Webhook 事件名称，因为它们可能会变更。请参阅控制台中的 Webhook 配置以获取当前可用事件列表。
Webhook 负载遵循 Waffo Pancake 的标准约定：
  • ID 为 UUID v4 格式
  • 金额以显示格式字符串表示
  • 时间戳为 ISO 8601 UTC 格式
  • 计费频率使用 billingPeriod 字段（例如 monthly、yearly）

​
客户门户

让客户自助管理订阅：
  • 查看详情
  • 更新支付方式
  • 更换方案
  • 取消
  • 恢复订阅
  • 下载发票

客户门户

自助式订阅管理。

​
最佳实践

年付优惠 15-20% = 降低流失率 + 改善现金流。
续费未成功 ≠ 立即取消。给客户时间更新支付方式并完成恢复。
试用即将到期、即将扣款。不要让客户感到意外。