> ## 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.

# 订阅产品端点

> 创建和管理订阅产品及产品组

订阅产品支持可配置计费周期和多币种定价的周期性计费。产品可以组织到产品组中，实现共享试用管理和分层定价方案。

## 计费周期

| 周期          | 频率      |
| ----------- | ------- |
| `weekly`    | 每 7 天   |
| `monthly`   | 每个日历月   |
| `quarterly` | 每 3 个月  |
| `yearly`    | 每 12 个月 |

## 产品组对象

产品组将相关的订阅产品组织在一起（如免费版、专业版、企业版），并实现组内产品间的共享试用管理。每个组按环境存在 -- 测试和生产各一行。

```json theme={"system"}
{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "storeId": "STO_2D5F8G3H1K4M6N9P",
  "name": "Pricing Plans",
  "description": "Free, Pro, and Enterprise tiers",
  "rules": { "sharedTrial": true },
  "productIds": [
    "PROD_3F7H2J5L8N1Q4S6U",
    "PROD_8B4D6F9H2K5M7P1R",
    "PROD_1C3E5G7J0L2N4Q6S"
  ],
  "environment": "test",
  "createdAt": "2026-03-30T10:30:00.000Z",
  "updatedAt": "2026-03-30T10:30:00.000Z"
}
```

<Note>
  产品组 ID 使用 **UUID 格式**，而非 Short ID 格式。这是 API 中唯一使用原始 UUID 的实体。
</Note>

| 字段            | 类型             | 说明                      |
| ------------- | -------------- | ----------------------- |
| `id`          | string         | 产品组 ID（UUID 格式）         |
| `storeId`     | string         | 门店 ID（`STO_xxx` 格式）     |
| `name`        | string         | 产品组名称（每个门店 + 环境唯一）      |
| `description` | string \| null | 产品组描述                   |
| `rules`       | object         | 产品组规则（见下方）              |
| `productIds`  | string\[]      | 产品 ID 列表（`PROD_xxx` 格式） |
| `environment` | string         | `test` 或 `prod`         |
| `createdAt`   | string         | ISO 8601 时间戳            |
| `updatedAt`   | string         | ISO 8601 时间戳            |

### 规则

| 字段            | 类型      | 默认值     | 说明                                                  |
| ------------- | ------- | ------- | --------------------------------------------------- |
| `sharedTrial` | boolean | `false` | 设为 `true` 时，试用使用记录在组内所有产品间共享。防止客户通过切换同组产品来重复获取免费试用。 |

## 端点

<CardGroup cols={2}>
  <Card title="创建产品" icon="plus" href="/api-reference/endpoints/subscription-products/create-product">
    创建带有计费周期和多币种定价的订阅产品。
  </Card>

  <Card title="更新产品" icon="pen" href="/api-reference/endpoints/subscription-products/update-product">
    更新订阅产品内容。如有内容变更，创建新的不可变版本。
  </Card>

  <Card title="发布产品" icon="rocket" href="/api-reference/endpoints/subscription-products/publish-product">
    将订阅产品从测试发布到生产（仅限首次发布）。
  </Card>

  <Card title="更新状态" icon="toggle-on" href="/api-reference/endpoints/subscription-products/update-status">
    激活或停用订阅产品。
  </Card>

  <Card title="创建产品组" icon="layer-group" href="/api-reference/endpoints/subscription-products/create-group">
    创建产品组以组织相关订阅产品。
  </Card>

  <Card title="更新产品组" icon="pen-to-square" href="/api-reference/endpoints/subscription-products/update-group">
    更新产品组的名称、描述、规则或产品列表。
  </Card>

  <Card title="删除产品组" icon="trash" href="/api-reference/endpoints/subscription-products/delete-group">
    永久删除产品组。
  </Card>

  <Card title="发布产品组" icon="rocket" href="/api-reference/endpoints/subscription-products/publish-group">
    将产品组从测试发布到生产（支持重复 UPSERT）。
  </Card>
</CardGroup>