订阅 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。
订阅对象
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 订阅计入活跃支出。
自然语言示例
新增订阅
用户意图:修改计费周期
用户意图:- 调用
GET /api/v1/subscriptions找到 Netflix 记录。 - 向用户确认具体记录和修改内容。
- 调用
PATCH /api/v1/subscriptions/{id}。
删除重复记录
用户意图:- 调用
GET /api/v1/subscriptions找到重复候选。 - 向用户确认订阅名称和 id。
- 调用
DELETE /api/v1/subscriptions/{id}。
自定义计费周期
如果不是月付或年付,把period 设为 custom,并把 customDate 设为表示天数的正整数字符串。
customDate 设为 "30";不要选择 monthly。从 custom 改回 monthly 或 yearly 时省略 customDate,服务端会自动清理旧的自定义计费数据。