跳转到主要内容

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.

​
产品 = 计费对象

在 Waffo Pancake 中，产品（Product） 是用于结账、计税和归档的计费对象。它不是单纯的展示卡片，也不等同于传统电商 SKU。
更专业的理解方式是：产品是你对外销售的标准化收费单元，可以是固定价格产品、订阅方案，或被动态定价复用的基础计费对象。

​
核心建模方式

一次性付款

用户为预设价格支付一次。
  • 数字下载
  • 终身许可证
  • 模板、课程、素材

订阅制

用户按固定周期持续支付。
  • SaaS 方案
  • 会员制
  • 服务合同

动态定价

金额在结账时计算。
  • 超额用量
  • 充值包
  • 按报价收费

​
创建产品

控制台 → 产品 → 创建产品 
{
  "storeId": "your-store-uuid",
  "name": "Pro Plan",
  "prices": {
    "USD": { "amount": "29.00", "taxIncluded": false, "taxCategory": "saas" }
  }
}
完成。 你会得到一个固定价格产品的购买链接，或得到一个可复用的计费对象用于程序化结账。

​
产品字段

​
必填项

字段说明
名称你的消费者看到的内容
价格收费金额
货币USD、EUR、GBP、CNY、JPY、HKD 等
类型一次性收费或订阅计费
商品类别SaaS、数字商品、软件等

​
选填项

字段默认值用途
描述—Markdown 格式，用于推销产品
图片—推荐 400x400px
成功跳转 URL—购买后重定向地址

​
动态定价

当最终收费金额要在运行时计算时，应使用动态定价。 典型场景：
  • 超额用量收费
  • 可变额度充值
  • 按合同报价收费
  • 服务端实时计算折扣后的金额

​
实现方式

  1. 在 Waffo 中创建一个基础一次性产品
  2. 在服务端计算最终金额
  3. 创建 Checkout Session 时传入 priceSnapshot
const session = await client.checkout.createSession({
  storeId: "store_id",
  productId: "usage-overage-product-id",
  productType: "onetime",
  currency: "USD",
  priceSnapshot: {
    amount: calculatedAmount,
    taxIncluded: false,
    taxCategory: "saas",
  },
});
priceSnapshot 会覆盖该次结账使用的产品价格。它必须由服务端生成，不能从不可信的客户端直接传入。
如果收费是事件型、按实际发生量计算的，即使客户本身属于订阅用户，这笔收费也应继续建模为一次性收费。

​
免费试用

让客户在购买前试用订阅产品。

​
试用滥用保护

Waffo Pancake 在平台层面自动追踪消费者的试用历史。当消费者开始新的订阅时，平台会根据其历史记录计算最大可用试用天数——无需商户做任何额外操作即可防止重复试用滥用。 商户也可以通过 API 传递 requested_trial_days 来为特定客户缩短或跳过试用期。
有效的试用滥用防护需要 buyerIdentity。使用认证式结账确保每个买家对每个产品只能领取一次试用。

​
计费周期

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

​
结账链接

购买链接也可以通过 API 创建结账会话生成： 
POST /v1/actions/checkout/create-session
生成的结账 URL 格式如下： 
https://checkout.waffo.ai/{store-slug}/{product-slug}
绑定到你的网站：
  • 网站按钮
  • Twitter 简介
  • 邮件签名
  • Discord 服务器
生成结账 URL：
  • 控制台：点击任意产品的”复制链接”
  • API：使用产品 ID 创建结账会话
测试与正式环境：
  • 在控制台顶部切换测试模式
  • 测试模式会生成测试环境的结账会话

​
产品状态

Active

已上线，客户可以购买。

Inactive

已隐藏，现有订阅继续有效。

​
更新产品

产品采用不可变版本控制：
更新会创建新版本。现有订阅保持其原始版本不变。
字段影响
名称/描述创建新版本
图片创建新版本
价格仅影响新购买
计费周期创建后无法更改

​
环境同步

在测试和生产环境之间同步产品版本： 
POST /v1/actions/onetime-product/publish-product
{
  "id": "product-uuid"
}

​
最佳实践

包含计费周期：
  • “Pro Plan - Monthly”
  • “Pro Plan - Annual (Save 20%)”
  • 使用整数价格（29，而非29，而非 28.73）
  • 年付折扣（15-20%）
  • 研究竞争对手
  • 最小 400x400px
  • PNG 或 JPG 格式
  • 小于 2MB