shoplazza-billing

shoplazza CLI — 账单模块

重要 — 首先使用 Read 读取 ../shoplazza-common/SKILL.md。 其中定义了所有跨领域机制：访问层级、输出封装（.data）、--dry-run、 --jq、schema、api rest、身份验证 / 配置文件，以及安全协议。本文件仅涵盖 账单领域，不会重复这些内容。

概述

账单模块让应用开发者可以向商家收取应用使用费用：一次性费用、 定期订阅费用和按量计费的使用量费用（以及交易记录）。它仅包含 叶子级规范命令——没有 +shortcuts。每笔费用都会动用真实资金，因此要先用 --dry-run，并在执行前向用户重述费用（shoplazza-common → 安全）。

费用采用两阶段流程：仅执行 create 不会转移资金——费用会保持待处理状态，直到 商家打开响应返回的审批 URL（一次性费用使用 confirm_url，定期费用使用 confirmation_url），并在 Shoplazza 管理后台批准费用，之后商家会跳转到你的 return_url。使用量费用无需审批——它们会计入已获批准的定期费用。

命令映射

意图 → 命令。权威参数 / 请求体定义位于 shoplazza schema billing.<group>.<cmd>。

用户意图	命令
创建一次性费用（涉及资金 → 先用 --dry-run）	billing one-time create --data '{"application_charge":{"name":"…","price":"<amt>","return_url":"…"}}' --dry-run
获取 / 列出一次性费用	billing one-time get --params '{"charge_id":"<id>"}' · billing one-time list
一次性费用交易	billing one-time transactions --params '{"charge_id":"<id>"}'
创建定期（订阅）费用（涉及资金 → 先用 --dry-run）	billing recurring create --data '{"recurring_application_charge":{"name":"…","price":<amt>,"return_url":"…"}}' --dry-run（可选 trial_days、capped_amount、terms）
获取 / 列出定期费用	billing recurring get --params '{"charge_id":"<id>"}' · billing recurring list
更新定期费用	billing recurring update --params '{"charge_id":"<id>"}' --data '{"recurring_application_charge":{…}}'
取消定期费用（先用 --dry-run）	billing recurring cancel --params '{"charge_id":"<id>"}' --dry-run
定期费用交易	billing recurring transactions --params '{"charge_id":"<id>"}'
在定期费用下记录一笔使用量费用（涉及资金 → 先用 --dry-run）	billing usage create --params '{"charge_id":"<id>"}' --data '{"usage_charge":{"description":"…","price":<amt>}}' --dry-run
获取 / 列出使用量费用	billing usage get --params '{…}' · billing usage list --params '{"charge_id":"<id>"}'
获取一笔应用费用交易	billing transactions get --params '{"transaction_id":"<id>"}'

处理请求

账单写入会动用真实资金。执行任何创建 / 取消操作前：

1. 将意图与具体叶子命令匹配（此处不能走捷径）。
2. 检查必填字段——缺少时，使用 AskUserQuestion 询问，绝不捏造金额：
   • 一次性 create：name、price、return_url
   • 周期性 create：name、price、return_url
   • 按用量 create：charge_id（父级周期性收费）、description、price
   • 周期性 cancel：charge_id
3. 先执行 --dry-run，复述（“向商家收费 $X——一次性收费 / 每月订阅 $X / CHG… 下的用量收费；返回至 ；在商家通过返回的确认链接批准前，收费处于待处理状态”），停下并等待用户同意，然后再执行。 对于 cancel，要复述取消的具体内容，不能只重复 ID：先执行 recurring get （名称 / 价格 / 状态——也能发现已取消的收费），并在同一条回复中提供 cancel --dry-run 预览。
4. 一次性 / 周期性 create 成功后，将批准 URL 交给用户——使用 --jq '.data.application_charge | {id, status, confirm_url}'（一次性） / --jq '.data.recurring_application_charge | {id, status, confirmation_url}'（周期性）—— 并明确说明：商家打开链接并批准前，不会扣款。
5. 如果平台拒绝收费，绝不要改用其他金额重试。 价格被拒绝通常是商品配置问题（见“注意事项”），而不是需要尝试的数值——试探不同金额可能会创建用户从未批准的收费。报告拒绝情况，指出所需的 partner-backend 配置，然后停止。

边界

看起来像账单，实际上属于其他功能：

看起来像账单	实际属于	命令
交易记录 = 买家给店铺付的钱 / 订单付款交易	shoplazza-orders	orders transactions
订单退款 / 为买家退款	shoplazza-orders	orders +refund

billing transactions = 应用向商家收取的费用；买家为订单付款则使用 orders transactions。（用于处理 app-charge-transactions / order-payment-transactions 路由冲突。）

权限 · Scope

Billing 无需店铺 scope。 auth login --domain billing 会扩展为 零个 scope—— 这是正确行为，不是 bug：应用收费端点由应用安装本身授权， 而不是由店铺 OAuth 授权。已进行线上验证——在既没有 read_finance 也没有 write_finance 的 profile 上，recurring list 返回了 ok:true，而 recurring create 进入了业务校验（400 / 422），没有返回 401/403。

因此不要运行 auth login --domain billing。 授权会在服务器端替换现有授权， 所以零 scope 登录可能会撤销其他域依赖的 scope。此处出现 401/403，表示 账号登录缺失或已过期——检查 auth status，不要继续追查 scope。

注意事项

仅适用于特定领域（通用的 .data / --dry-run / --jq 规则见 shoplazza-common）。

症状	原因	解决方法
price 类型导致扣款被拒绝	不同扣款类型的 price 类型不同：单次 = 字符串（"99.99"），定期和按用量 = 数字（29、0.05）	使用匹配的类型 — 单次扣款加引号，定期／按用量扣款使用不带引号的数字
create 成功，但商家始终未被扣款	扣款分两阶段进行：create 会返回一笔待处理扣款；只有商家通过返回的批准 URL 批准后，扣款才会生效	将 URL 提供给用户，并说明商家批准前不会扣款 — create 返回 ok:true 不代表“已扣款”
用 jq 提取批准 URL 时返回 null	字段名称因扣款类型而异：单次扣款 = confirm_url，定期扣款 = confirmation_url（按用量扣款两者都没有 — 无需批准）	根据扣款类型匹配字段
没有扣款时 usage create 失败	charge_id（父级定期扣款）是必填路径参数	--params '{"charge_id":"<recurring charge id>"}'
未预览就创建了真实扣款	扣款会产生真实费用	先使用 --dry-run，向用户复述操作内容，等待用户同意后再执行
recurring create → 422 The price configuration in the plan does not match with the listing, please check	平台只接受与应用商品刊登（合作伙伴后台）中配置的定价方案匹配的价格；任意金额都会被拒绝。无法通过 CLI 修复 — 此模块没有商品刊登／方案端点（schema billing 已确认）	告知用户在应用商品刊登中添加／调整该方案，然后原样重新运行同一命令。不要尝试其他价格
recurring create → 纯粹的 400 Bad Request，没有字段信息，且请求正文符合 schema	添加 capped_amount 会让后端改为返回具体的 422 错误（已在线验证：相同请求正文 + capped_amount → 上述商品刊登 422 错误）。400 是否源于同一原因，或是由其自身的 capped_amount 检查导致，尚未确认 — schema 将该字段标记为可选	不要尝试查找格式错误的字段 — 重新发送一次并加上 capped_amount，以显示实际错误信息，然后据此处理。这是诊断手段，不是修复方法：不要用其他价格重试，也不要认为设置该字段后扣款就一定会成功

操作示例

# 1. One-time $99.99 setup fee (price is a STRING)
billing one-time create --data '{"application_charge":{"name":"Setup Fee","price":"99.99","return_url":"https://app.example.com/billing/done"}}' --dry-run
# real run: add --jq '.data.application_charge | {id, status, confirm_url}' and hand the URL over

# 2. Recurring $29/mo subscription, 7-day free trial (price is a NUMBER)
billing recurring create --data '{"recurring_application_charge":{"name":"Pro Plan","price":29,"return_url":"https://app.example.com/billing/ok","trial_days":7}}' --dry-run
# real run: add --jq '.data.recurring_application_charge | {id, status, confirmation_url}'

# 3. Usage charge $0.05 under recurring charge CHG7788 (price NUMBER)
billing usage create --params '{"charge_id":"CHG7788"}' --data '{"usage_charge":{"description":"API calls overage","price":0.05}}' --dry-run

# 4. Cancel a recurring charge: look up what it is, preview, then STOP for the user's go-ahead
billing recurring get --params '{"charge_id":"CHG5566"}' --jq '.data.recurring_application_charge | {name, price, status}'
billing recurring cancel --params '{"charge_id":"CHG5566"}' --dry-run

参考资料

• 各命令的标志：shoplazza billing <group> <cmd> --help
• 参数／请求正文／响应：shoplazza schema billing.<group>.<cmd>
• 通用机制（身份验证／层级／输出封装／--dry-run／安全）：../shoplazza-common/SKILL.md