SuperAPI AI 工具集

schedules

通用与其它

查看项目

更新于 10-16 07:16

技能介绍

用途:schedule 让客户按带日期的阶段在多个 plan 之间迁移。用 createSchedule 创建,用 previewCreateSchedule 预览。

替换行为:一个客户只持有一个 schedule。再次调用 createSchedule 会整体替换它,旧阶段及其已排定 plan 会被删除。没有更新或删除接口。要修改就重发完整阶段列表,包括已开始的阶段;只保留即时阶段即可去掉未来阶段。schedule 从未安排的 plan(例如单独附加的 add-on)始终保留。

阶段计时:每个阶段必须且只能有一个 starts_at(epoch 毫秒或 "now")或 starting_after({ duration_type: "month" | "year", duration_count })。starts_at:"now" 仅限第一阶段,starting_after 不允许用于第一阶段。第一阶段必须现在开始:未来的 first starts_at 会被拒绝;过去的仅在付费周期 plan 且客户无现有 Stripe 订阅时可用。starts_at 值必须严格递增。注意:除非传入 billing_cycle_anchor,晚于当前计费周期边界 12 小时内的阶段会被静默吸附到该边界。

阶段内 plan:plans:[{ plan_id, entity_id?, feature_quantities?, version?, customize? }]。每个阶段每个 group 与 scope 最多一个主 plan,add-on 不受限。entity_id 设定 scope:省略则继承请求实体,传 null 表示客户级。第一阶段固定 scope,后续阶段不可更改。此处的 customize 拒绝 free_trial 与 license key,试用应在顶层设置。unscheduled_plans 随即时阶段计费,不会被后续阶段过期或替换;阶段声明的 group 与 scope 重复会报错。

即时阶段参数:free_trial、currency、discounts、invoice_mode、billing_cycle_anchor:"now"、redirect_mode 仅作用于即时阶段。free_trial 作用于该阶段所有周期 plan,schedule 不支持 on_end:"revert"。后续阶段 billing_cycle_anchor:"phase_start" 会在该阶段开始时重置 Stripe 计费周期。enable_plan_immediately:true 在 Stripe 结账仍挂起时即授予访问权;响应返回 status:"pending_payment" 且 schedule_id 为 null,结账完成后 schedule 才持久化。no_billing_changes:true 只在 Autumn 写入 schedule,不动 Stripe。