产品与功能

定义你的销售内容。创建包含一个或多个变体的产品，附加可复用的功能以实现基于权限的访问控制。

Proyecta Commerce 使用三个核心概念：产品、变体和功能。

产品 — 你所销售的东西（例如”Pro 计划”、“T 恤”、“战略咨询”）
变体 — 产品的定价层级或配置（例如”Pro 月付 $29”、“Pro 年付 $290”、“T 恤 – 大码”）
功能 — 应用在运行时检查的可复用权限键（例如 pro_features、unlimited_projects、api_access）

一个产品可以拥有多个变体。产品还可以附加一个或多个资源——通常是功能——在客户订阅后授予相应的访问权限。

创建产品

在 Dashboard > Commerce > Products 中，点击 Create product（或直接告诉 AI："Create a Pro plan at $29/month and a Business plan at $99/month."）。每个产品需要填写：

展示名称（例如”Pro”）
至少一个变体

变体

每个变体拥有独立的定价信息：

字段	说明
`name`	变体的展示标签（“Monthly”、“Annual”、“Large”）
`currency`	三字母 ISO 货币代码 — USD、EUR、GBP、JPY、BRL、MXN、INR……（SDK 支持 130+ 种货币）
`unit_amount`	以最小货币单位（分）表示的价格。`2900` = $29.00
`recurring`	可选 — `{ interval: 'week' \| 'month' \| 'year' }`。一次性收费则省略此字段。暂不支持按天计费。
`is_default`	已接受但尚未生效 — 默认变体选择功能暂未实现。
`media`	通过 CDN 文件 ID 附加图片或视频（参见文件）

定价不可更改。 变体一旦创建，其价格便无法修改——请创建新的变体来替代。这可以防止因误操作而影响现有订阅者的价格。

功能（权限）

功能是访问控制的基本单元。创建一次功能后，即可将其附加到一个或多个产品上。

// Create a feature
const pro = await proyecta.commerce.features.create({
    name: 'Pro features',
    description: 'Unlocks the Pro tier capabilities',
    // optional custom id — lowercase alphanumeric and underscores only (e.g. 'pro_features')
});

创建产品时，你可以通过”resources”将功能附加到产品上。订阅该产品的客户将获得其附加的所有功能的访问权限。

然后，在你的应用中检查客户是否拥有访问权限：

const { has_access } = await proyecta.commerce.check({
    customer_id: 'cus_123',
    resource_id: 'pro_features',
});

注意： resource_id 必须使用功能的键——即由功能名称派生出的 slug（例如 pro_features），而非 features.create() 返回的功能对象的 .id 属性。

这就是你在应用代码中对仅限 Pro 用户的页面、API endpoint 或功能进行访问控制的方式。

常见产品形态

SaaS 订阅

Create products: Free ($0/month), Pro ($29/month, $290/year), Business ($99/month, $990/year).
Attach a 'pro_features' feature to Pro and Business so I can gate access in my code.

实体商品

Create a T-shirt product with three variants: Small, Medium, Large at $25 each.

数字商品

Create a course product with a single one-time variant at $149.

捐款

Create a donation product with three variants: $25, $50, $100 — all one-time.

库存管理

Proyecta Commerce 目前不支持实体产品的库存追踪。如果你销售有库存的商品，请在应用数据库中自行管理库存数量，并在结账流程中进行校验。

即将推出

结账字段自定义 — 向买家收集额外信息
随心定价
实体产品内置库存追踪