用途
Billing 技能用于处理所有更新客户计费状态的请求。它要求 AI 助手在每次此类请求中都严格遵循既定步骤,覆盖大多数计费变更场景。
主要能力
- 根据当前状态与目标套餐 ID 决定操作:目标套餐已在该客户或实体上生效则使用 updateSubscription;迁移到不同套餐 ID 则使用 attach 或 multiAttach;分多个阶段(如 ramp、分阶段定价)迁移则使用 createSchedule。
- 读取客户当前状态时,要求将 getAgentRules、getCustomer、listEntities 与 verify 合并为一次批量调用,而非逐个调用。组织的 agent rules 可覆盖默认设定。verify 会对比 Autumn 预期与实时 Stripe,如返回不一致需向用户标记。
- 按需提前加载相关技能:涉及试用或客户正在试用时先加载 trials;涉及随时间在套餐间迁移或客户已有 schedule 时先加载 schedules;涉及 cap、limit、overage、credit allowance 或客户已有计费控制时先加载 balances。
计费行为与付费方式
遵循用户指令或组织规则;若两者均未说明,默认将运营主导的计费操作设为发票模式:invoice_mode.enabled: true、invoice_mode.finalize: false,并立即授予访问权限。即使即时扣款为 $0 也使用发票模式,除非用户要求 checkout、自助或直接扣款。该模式会立即授予访问权限,同时创建可审核、编辑和发送的 Stripe 草稿发票。net terms 仅在用户或合同明确时使用 invoice_mode.net_terms_days,否则不主动询问。若客户没有邮箱,需先询问并更新客户,再预览发票或 checkout 流程。
立即启用套餐
顶层 enable_plan_immediately 可在付款被延迟或待处理时(发票未付、checkout 未完成或未来 starts_at)立即授予访问权限,是 invoice_mode.enable_plan_immediately 的超集(后者仅覆盖发票未付情形)。createSchedule 与 attach 应设置顶层 enable_plan_immediately: true;updateSubscription 没有顶层字段,仍使用 invoice_mode.enable_plan_immediately。
Checkout 流程
仅当用户想要发送给客户的支付链接或 checkout 会话时使用 checkout。使用时省略 invoice_mode,设置 redirect_mode: "always",并设置 enable_plan_immediately: true。若用户可能想要 checkout 但未明确说明,预览前先确认。
直接扣款流程
若用户想要自助式计费或立即从卡扣款,在省略 invoice_mode 前先确认。省略 invoice_mode 时,符合条件的套餐变更可能立即向客户扣款。
按比例计费(Proration)
默认将 proration 设为 none,使预览开始时没有即时的按比例扣款或信用额度。若客户没有现有订阅,不要传 proration_behavior: "none",新订阅不允许该设置。按端点使用字段名:attach/updateSubscription 用 proration_behavior,createSchedule 用 billing_behavior。仅当用户要求按比例计费、立即结算差额或即时信用/扣款时使用 prorate_immediately。
构建请求体
客户特定定价放在 customize 中——它是对目录套餐的补丁而非替换,使用 add_items 与 remove_items,不要替换整个 items 数组。示例:
{ "customize": { "remove_items": [{ "feature_id": "credits" }], "add_items": [{ "feature_id": "credits", "included": 5000 }] } }
add_items 是完整条目定义,需先从套餐上读取该条目的字段(pooled、reset、rollover 等)并逐一重述,除非明确指定。基础价格变更放在 customize.price。每个 remove 条目是一个过滤器,当仅凭 feature_id 可能匹配多个条目时,需补充 billing_method、interval 或 interval_count 以锁定正确条目。
预览与写入
调用对应的 preview:previewAttach、previewCreateSchedule 或 previewUpdateSubscription。若返回正常,在同一轮次调用写入,中间不输出文字(写入调用即展示审批卡)。若预览失败,说明阻塞原因一次后停止。当请求需要多次写入时(如先改邮箱再 attach、先创建 reward 再 attach),应将其合并在单次批量中,以便用户只审批一次。先运行所有需要的预览,再一起发送所有写入。
撰写审批说明
以要点列出正在发生的事,每步一行,按步骤适用顺序排列。说明客户会有什么变化、支付什么、何时生效。对于批量请求,在每个写入上重复相同的完整说明。
报告结果
写入在轮次之外运行,结果通过 <approval_applied> 块返回。说明已应用,然后以 markdown 要点列出链接。每个链接都应是带简短标签的超链接——View invoice、Stripe customer——不要直接粘贴裸 URL。若 invoice.status 为 draft,需说明必须在其中完成 finalize 后才会向客户扣款。若失败,说明并引用错误,未应用的变更不提供链接。若客户操作有误并需要撤销某项操作,引导其前往 dashboard。然后继续执行用户请求中尚未完成的其余步骤。
限制与待补充信息
关于该技能的具体收费、价格、平台支持范围及实际效果,资料中暂未提供。