跳转到主要内容

订阅 CRUD

订阅 API 使用 camelCase 字段。服务端管理字段会在响应中返回,但不能出现在写请求里。

操作语义

AI 集成在更新或删除前应先查询并确认目标订阅,除非用户已提供准确的订阅 UUID。写操作需要带 write 权限的 API Key;只读 Key 会收到 403 insufficient_scope。

分页

GET /api/v1/subscriptions 默认按创建时间倒序返回,支持两个可选查询参数: 响应中包含 pagination 对象。当 hasMore 为 true 时,用 offset + limit 获取下一页。
超出范围的取值会返回 400 invalid_pagination。

过滤、排序与自动续费周期滚动

GET /api/v1/subscriptions 在分页之外,还支持以下可选过滤器和排序:
[!NOTE] 续费日期动态跨周期推进: GET /api/v1/subscriptions 与 GET /api/v1/subscriptions/{id} 会自动将已过期的 active 非试用订阅按完整计费周期推进到当前周期的下次扣款日(与网页仪表盘和 Bark 定时提醒一致),并在执行 expiringBefore 过滤和 sort=nextPaymentDate 排序前生效。免费试用(isTrial: true)以及 paused / cancelled 记录绝不会自动顺延。
将 status=active 与 expiringBefore 组合即可回答「哪些即将续费」。非法取值返回 400 invalid_query,并带 field 与 suggestedFix。
响应会回显实际生效的查询,便于 Agent 确认结果来源:

订阅对象

当 isTrial 为 true 时,对象还会包含 "trialEndsOn": "YYYY-MM-DD";当 period 为 "custom" 时,包含 "customDate": "<天数>"。

可写字段

服务端管理字段包括 id、status(网页端生命周期状态)、createdAt 和 updatedAt。不要在 POST 或 PATCH 请求里发送这些只读字段(发送 status 或 id 会返回 400 invalid_subscription_field)。

字段规则

nextPaymentDate 是权威的订阅计划日期。月付订阅通过 billingAnchorDay 保留原始日历日期,短月份只会临时落到月末,例如:1 月 31 日 → 2 月 28/29 日 → 3 月 31 日。如果服务是固定每 30 天扣费而非每月固定日扣费,请使用 period: "custom" 和 customDate: "30"。

免费试用(Free Trials)

记录尚未首次扣款的免费试用时,将 isTrial 设为 true 并传入 trialEndsOn(同时将 nextPaymentDate 设为同一天):
免费试用是一次性截止日期:trialEndsOn 过期后不会自动顺延到下个月,直到你手动转为正式订阅({"isTrial": false, "nextPaymentDate": "2026-08-10"})或删除记录。

状态 vs 删除

响应中会返回只读的 status(active、paused、cancelled),列表查询也可以按它过滤。公开 API 不能 通过写入 status 来取消、暂停或恢复订阅,也不会替你在外部服务商处退订。 调用 DELETE /api/v1/subscriptions/{id} 会从你的订阅账本中永久移除该记录,并在审计日志中写入一条包含 metadata.before 快照的 subscription.delete 记录。 在分析端点中,只有 active 订阅计入活跃支出。

自然语言示例

新增订阅

用户意图:
API 调用:

修改计费周期

用户意图:
Agent 流程:
  1. 调用 GET /api/v1/subscriptions 找到 Netflix 记录。
  2. 向用户确认具体记录和修改内容。
  3. 调用 PATCH /api/v1/subscriptions/{id}。

删除重复记录

用户意图:
Agent 流程:
  1. 调用 GET /api/v1/subscriptions 找到重复候选。
  2. 向用户确认订阅名称和 id。
  3. 调用 DELETE /api/v1/subscriptions/{id}。

自定义计费周期

如果不是月付或年付,把 period 设为 custom,并把 customDate 设为表示天数的正整数字符串。
固定每 30 天续费时,把 customDate 设为 "30";不要选择 monthly。从 custom 改回 monthly 或 yearly 时省略 customDate,服务端会自动清理旧的自定义计费数据。

AI tool schema

使用 ai-tools.json 获取 tool/function 定义、风险等级和确认提示。