> ## 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）** 是用于收银台、计税和归档的对象。它是你对外收费的商业化"报价单"，而不仅仅是一张展示卡片。

<Note>
  更专业的理解方式是：把产品视为计费实体：

  * 一个固定价格的报价
  * 一个订阅方案
  * 或一个用于收银台动态定价的基础产品
</Note>

***

## 核心建模方式

<CardGroup cols={3}>
  <Card title="一次性付款" icon="cart-shopping">
    用户为预设价格支付一次。

    * 数字下载
    * 终身许可证
    * 模板、课程、素材
  </Card>

  <Card title="订阅制" icon="repeat">
    用户按固定周期持续支付。

    * SaaS 方案
    * 会员制
    * 服务合同
  </Card>

  <Card title="动态定价" icon="slider">
    金额在收银台时计算。

    * 超额用量
    * 充值包
    * 按报价收费
  </Card>
</CardGroup>

***

## 创建产品

控制台 → 产品 → **创建产品**

```json theme={"system"}
{
  "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 | —   | 结账完成后客户的落地地址。支付成功与失败都使用同一个地址 — 只支持配置一个。 |

### 价格限制

每种币种都有可设置的最低和最高价格，超出范围的价格在保存商品时会被拒绝。

| 币种  |       最低 |            最高 |
| --- | -------: | ------------: |
| USD |   \$1.00 |    \$7,500.00 |
| EUR |    €1.00 |     €7,400.00 |
| GBP |    £1.00 |     £6,400.00 |
| JPY |     ¥100 |    ¥1,250,000 |
| HKD | HK\$8.00 | HK\$61,000.00 |

<Note>
  CNY 可以在 dashboard 的分析视图中作为展示币种使用，但目前不支持作为商品定价币种。
</Note>

***

## 动态定价

当最终收费金额要在运行时计算时，应使用动态定价。

典型场景：

* 超额用量收费
* 可变额度充值
* 按合同报价收费
* 服务端实时计算折扣后的金额

### 实现方式

1. 在 Waffo Pancake 中创建一个**基础一次性产品**
2. 在服务端计算最终金额
3. 创建 Checkout Session 时传入 `priceSnapshot`

```typescript theme={"system"}
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",
  },
});
```

<Warning>
  `priceSnapshot` 会覆盖该次收银台使用的产品价格。它必须由服务端生成，不能从不可信的客户端直接传入。
</Warning>

<Tip>
  如果收费是事件型、按实际发生量计算的，即使客户本身属于订阅用户，这笔收费也应继续建模为一次性收费。
</Tip>

***

## 免费试用

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

### 试用滥用保护

Waffo Pancake 在平台层面自动追踪消费者的试用历史。当消费者开始新的订阅时，平台会根据其历史记录计算最大可用试用天数——无需商户做任何额外操作即可防止重复试用滥用。

商户也可以通过 API 传递 `requested_trial_days` 来为特定客户缩短或跳过试用期。

<Warning>
  有效的试用滥用防护需要 `buyerIdentity`。使用[认证式收银台](/zh/integrate/sdks#authenticated-checkout-recommended)确保每个买家对每个产品只能领取一次试用。
</Warning>

***

## 计费周期

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

<Tip>
  年付方案打 15-20% 折扣 = 更低的流失率 + 更好的现金流。
</Tip>

***

## 产品购买链接

每个产品都拥有一个永不过期的固定购买链接：

```
https://checkout.waffo.ai/{store-slug}/{product-slug}
```

测试模式：

```
https://checkout.waffo.ai/{store-slug}/{product-slug}/test
```

**绑定到你的网站：**

* 网站按钮
* Twitter 简介
* 邮件签名
* Discord 服务器

**核心优势：**

* 链接是永久的——即使你更新产品信息，链接也保持不变
* 无需管理会话或令牌
* 客户打开链接时，收银台会话会自动创建

**生成你的链接：**

* **控制台**：在任意产品上点击"复制链接"
* **API**：在更高级的场景下，可通过 API 创建带自定义参数的 Checkout Session（动态链接，TTL 为 7 天）

**测试与正式环境：**

* 在控制台顶部切换测试模式即可使用测试链接进行预览
* 测试链接使用 `/test` 后缀

***

## 产品状态

<CardGroup cols={2}>
  <Card title="Active" icon="check">
    已上线，客户可以购买。
  </Card>

  <Card title="Inactive" icon="pause">
    已隐藏，现有订阅继续有效。
  </Card>
</CardGroup>

***

## 更新产品

产品采用**不可变版本控制**：

<Warning>
  更新会创建新版本。现有订阅保持其原始版本不变。
</Warning>

| 字段    | 影响      |
| ----- | ------- |
| 名称/描述 | 创建新版本   |
| 图片    | 创建新版本   |
| 价格    | 仅影响新购买  |
| 计费周期  | 创建后无法更改 |

### 环境同步

将产品版本从测试环境发布到生产环境：

```bash theme={"system"}
POST /v1/actions/onetime-product/publish-product
{
  "id": "product-id"
}
```

<Note>
  发布是单向的（测试 → 生产），只在首次发布时需要。
</Note>

***

## 最佳实践

<AccordionGroup>
  <Accordion title="命名">
    包含计费周期：

    * "Pro Plan - Monthly"
    * "Pro Plan - Annual (Save 20%)"
  </Accordion>

  <Accordion title="定价">
    * 使用整数价格（$29，而非 $28.73）
    * 年付折扣（15-20%）
    * 研究竞争对手
  </Accordion>

  <Accordion title="图片">
    * 最小 400x400px
    * PNG 或 JPG 格式
    * 小于 2MB
  </Accordion>
</AccordionGroup>