API 参考：订阅

周期性扣款——相对 Crypto Bot 的扩展。您建一个套餐（金额 + 周期），把它的授权链接发给 用户，之后平台每一期从他们的钱包余额里扣款，扣掉手续费之后给您的应用余额入账。通用约定见 商户 API 参考页面。

模型

套餐是一份不可变的快照：用户授权的那一份，就是这个金额、这个周期。要改价格，就建一个 新套餐并把旧的归档——现有订阅者仍然按他们授权过的条件续费。第一期在授权时扣。

续费款项在每期结束时自动扣除。续费失败（余额不足、账号受限）时，订阅进入 grace，平台在宽限期内 每小时重试一次（时长由平台设置）；若仍无法成功扣款，订阅状态变为 expired。商户应将 current_period_end 视为用户使用订阅服务的截止时间。在 grace 期间成功扣除续费款项时，下一期从原来的 current_period_end 开始，而不是从付款时间开始。

生命周期里的事件都有可订阅的 webhook：subscription_activated、 subscription_charged、subscription_cancelled、subscription_expired。进入 grace 时没有 webhook（订阅者会在 Telegram 里收到消息）；如有需要，请定期用 status=grace 查询 getSubscriptions。如果您的应用被删除，其订阅会在下次续费时以 cancelled_by: "merchant" 取消。

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan——权限范围 subscriptions。

参数	类型	必填	含义
name	string	是	1–64 个字符，显示给订阅者
asset	string	是	币种代码
amount	string	是	每期扣款额，正的小数字符串
period_days	integer	是	扣款周期天数，从平台最小值（周期过短时由 invalid_period 提示）到 365

返回的是套餐对象：plan_id、name、asset、amount、amount_minor、period_days、 archived、mini_app_subscribe_url——您发给用户去授权的那条 t.me 链接——以及 created_at。

错误：400 unknown_asset、400 invalid_amount、409 invalid_period（周期短于平台下限）、400 invalid_request（缺少 period_days、该值不是正数或超过 365；缺少 name、asset 或 amount 也会返回此错误）、503 subs_disabled（功能不可用）、409 too_many_plans（未归档的套餐最多 50 个——请先归档未使用的套餐，再创建新套餐）。

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans——权限范围 read，无参数。返回 {"items": [plan, …]}，按时间倒序，每一项多带一个字段：active_subscribers——该套餐上仍然 有效的（active + grace）订阅数。

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan——权限范围 subscriptions。一个参数：plan_id。 它阻止的是新的授权；现有订阅照样按各自的快照续费（要逐个终止，请用 cancelSubscription）。归档没法通过 API 撤销。返回的是更新后的套餐对象，archived: true。 错误：404 plan_not_found。

getSubscriptions

GET /pay/api/getSubscriptions——权限范围 read。过滤条件：plan_id、user_id、status （active / grace / cancelled / expired），外加 offset / count（默认 100，最大 500）。 返回 {"items": [subscription, …]}，按时间倒序。

订阅对象：subscription_id、plan_id、user_id（订阅者的 Telegram ID）、快照条件 （asset、amount、amount_minor、period_days）、status、auto_renew、period_no （已付期数）、current_period_start / current_period_end、created_at、cancelled_at、 cancelled_by（user 或 merchant）、expired_at。

cancelSubscription

POST /pay/api/cancelSubscription——权限范围 subscriptions。一个参数：subscription_id。 它停掉续费（cancelled_by: "merchant"）；已付的那一期到 current_period_end 之前照常能用， 状态立即变为 cancelled，订阅者会收到通知。只要套餐和应用仍可用，被取消的订阅者可通过同一链接重新授权。重新授权会立即扣款，并开始新的周期。返回的是更新后的订阅对象。

错误：404 sub_not_found、409 sub_not_active（已经取消或已经到期）。