销售产品和方案
你的产品带着价格出现在前台;买家购买后获得授权,并用 GitHub 用户名激活。
商店的售卖内容在后台定义。产品是买家获得授权的对象。方案是该产品在某一种语言下的一个价格。结账始终按方案上保存的价格收费。
准备工作
- 拥有
products.read和products.write的管理员账号,内置的 Commerce Manager 角色已包含这两项。 - 要收取真实款项,需要先接入支付服务商,见 接入支付服务商。
从预置目录开始
刚完成迁移的数据库没有任何商品,店面是空的。先写入售卖站自带的目录(Kernlift Premium 会员和各个业务模板),然后在此基础上修改:
pnpm db:seed-storefront该命令只插入缺失的行,重复执行不会产生变化,也不会覆盖你改过的文案与价格。预置价格只是示例,请按下面的步骤改成自己的定价。目录定义在 scripts/db/storefront-catalog.ts,售卖自己的产品时替换这个文件。
创建产品
打开表单
进入 商业化 → 产品(/admin/products),点击 新建产品。
描述产品
- 键:稳定的标识,只能使用小写字母、数字、连字符或下划线,例如
cms。保存后不能修改。 - 类型:底座 即会员商品(附带底座仓库,并解锁会员价);模板 是单独出售的业务模板。模块 和 全家桶 保留给按那种方式售卖的目录。
- 状态:在售 的产品会在前台列出;隐藏 和 下架 不会。
- 交付仓库(owner/name):买家激活后被邀请进入的 GitHub 私有仓库,例如
kernlift/image-studio。没有填写的商品会显示为尚未开放,无法购买。 - 依赖(逗号分隔的产品键) 与 全家桶(持有者可使用全部在售产品):会员和模板留空、不勾选。
- 每种语言的 名称、一句话卖点 和 描述。
保存
点击 保存产品,页面会打开该产品,以便继续添加方案。
添加方案
每个方案是一种语言下的一个价格,所以同时以英文和中文销售的产品,每种语言各有一行方案。
业务模板在每种语言下有两个方案:<key>-lifetime 是任何人都能支付的原价,<key>-member 是会员价。键以 -member 结尾的方案只有持有会员授权的账号可以结账,否则服务端会拒绝。
新建方案
在产品页面的 定价方案 卡片中点击 + 方案键。要编辑已有方案,点击它的按钮(显示为 方案键 · 语言)。
设置价格
- 方案键(例如
pro_monthly)和 语言,保存后都不能修改。 - 价格(分) 和 币种,例如
4900和usd。 - 周期:按月、按年、终身 或 一次性,显示在价格旁边。
- 结账模式:
payment为一次性收费,subscription为周期性收费。Stripe 创建的订阅按月计费。 - 包含积分:该方案的订单付款后发放一次的积分,见 用积分对用量计费。
- 方案状态:
active可以购买,deferred不能购买。
填写卡片文案
填写 名称、描述、按钮文案 和 按钮链接,可选填 AI 额度说明。在 功能列表(每行一项,以 - 开头表示不包含) 中每行写一项功能。
保存
点击 保存方案,页面显示 方案已保存。,结账立即使用新价格。每种语言重复一次。
产品在哪里展示
只有 状态 为 在售 的产品才会列出。/pricing 用一张卡片展示会员,并列出各模板的原价和会员价。访问者是会员时结账用会员价方案,否则用原价方案。访问者语言下没有价格大于零的启用方案时显示 暂未定价。
了解购买会获得什么
服务商确认付款后,买家会获得:
/app/billing中的发票;subscription方案还会生成一条订阅。- 方案的 包含积分,每笔订单只发放一次。
/app/licences(已购模板)中该方案产品的授权。
拿到授权还不等于拿到代码。买家在该页面填写自己的 GitHub 用户名并点击 激活,售卖站随即把该账号以只读权限邀请进商品的交付仓库。用户名在首次激活后不可更改;GitHub 的邀请 7 天后过期,可以在同一页面重新发送。
激活即视为交付:授权已激活的订单不能再退款;从未激活的订单可以退款,全额退款会撤销它的授权。在 商业化 → 授权 中撤销一条已激活的授权,会把该账号移出仓库。
邀请由你保存在 商业化 → 产品 页「GitHub 交付」区域的 GitHub 令牌发出,令牌需要对每个交付仓库有管理权限。没有令牌时,买家激活会被告知交付尚未配置,且不会记录任何状态。
要不经购买直接授予授权,在 商业化 → 授权(/admin/licences,需要 licences.write)中使用 授予授权。账号不能重复购买已持有的商品。
在自己的页面添加购买按钮
定价卡片会向结账 API 发起请求,你也可以在任意已登录页面这样做。请原样传入方案的价格、币种和模式,值不一致的请求会被拒绝。
const response = await fetch("/api/billing/checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
planKey: "growth",
checkoutMode: "subscription",
amountCents: 9900,
currency: "usd",
locale: "zh",
}),
});
const result = await response.json();
if (response.status === 409 && result.message) {
// result.status 为 unknown_plan、plan_inactive、amount_mismatch、
// product_mismatch、membership_required 或 already_owned
throw new Error(result.message);
}
if (result.checkoutUrl) window.location.assign(result.checkoutUrl);成功时 API 返回 201 和服务商站点上的 checkoutUrl。付款后买家回到 成功 URL,查询参数中带有 billing_order_id、billing_status 和 provider。不要把这些参数当作付款凭证,应以订单状态为准。
验证
在每种语言下打开 /pricing,确认显示了方案的价格。用测试卡购买,然后在 商业化 → 订单 中确认订单已付款,并在买家的 /app/licences 中看到可激活的授权。pnpm validate:github-delivery 检查会员价、激活、退款规则与撤销;pnpm validate:billing 检查结算只发放一次方案积分。
常见问题
产品没有出现在前台
产品的 状态 不是 在售。改为 在售 并点击 保存产品。
卡片显示暂未定价
该语言下没有价格大于零、状态为 active 的方案。为该语言添加或修改方案。
结账返回 409 和 amount_mismatch
请求中的金额、币种或模式与方案不一致。请原样传入方案的值。在后台修改方案后,期望金额立即变化。
结账返回 409 和 membership_required
请求使用了会员价方案(<key>-member),而账号没有会员授权。买家可以先成为会员,或用原价方案购买该模板。
结账返回 409 和 already_owned
账号已持有该商品的有效授权。请引导买家到 /app/licences 激活。
激活时提示交付尚未配置
商品没有填写 交付仓库,或没有保存 GitHub 令牌。在 商业化 → 产品 中补齐两者,再用「验证已保存的令牌」确认 GitHub 接受该令牌。