tl-openmeter-api

OpenMeter API

与项目无关的 OpenMeter REST API 参考。按 OpenAPI 3.0 规范中的官方 API 标签组织。

套件

技能	用途
tl-openmeter-api	本技能：REST API 参考
tl-openmeter-local-dev	本地开发环境设置：Docker、ngrok、Stripe App、Webhooks
tl-openmeter-api-mcp-server	用于从 Cursor 调用本地 OpenMeter 的 MCP 服务

使用场景

• “如何将事件接入 OpenMeter？”
• “创建一个带订阅的 OpenMeter 客户”
• “查询某个 Meter 的用量”
• “设置阈值告警通知规则”
• “管理账单发票”
• “安装 Stripe Marketplace 应用”
• 调试用量计量、账单或订阅生命周期

资源

• references/REFERENCE.md — 按官方标签整理的完整端点表
• references/billing.md — 发票生命周期、客户删除流程、费率卡
• references/notifications.md — 渠道、规则、事件、测试
• references/product-catalog.md — 计划、功能、附加项：版本管理、费率卡、发布生命周期
• assets/openapi-spec.json — 完整的 OpenAPI 3.0 规范（事实来源）

官方 API 标签

OpenMeter API 将端点组织为以下 15 个标签：

#	标签	说明
1	Apps	管理应用集成（列出、获取、更新、卸载）
2	App: Custom Invoicing	对接第三方发票和支付系统
3	App: Stripe	Stripe 账单支持（API 密钥、Webhook、结账）
4	Billing	账单配置、发票、客户覆盖项、待处理行项目
5	Customers	客户生命周期、应用数据、Stripe 关联、权益值
6	Debug	内部指标（Prometheus 格式）
7	Entitlements	用量限制、基于配额的定价、功能访问权限
8	Events	CloudEvents 接入与列表查询
9	Lookup Information	静态数据（货币、进度）
10	Meters	聚合规则、用量查询、分组依据
11	Notifications	阈值告警的渠道、规则、事件
12	Portal	通过限定范围的令牌提供面向消费者的用量仪表板
13	Product Catalog	计划、功能、附加项（版本管理、费率卡、发布生命周期）
14	Subjects	已弃用 — 请使用带有 usageAttribution.subjectKeys 的 Customers
15	Subscriptions	客户计划分配、取消、更改、迁移、恢复

---

Base URL 和身份验证

• Base URL： OPENMETER_URL（例如，本地环境为 http://localhost:8888，也可以是已部署的 URL）
• 身份验证： Authorization: Bearer <OPENMETER_API_KEY>。本地可自托管实例通常无需身份验证。
• Content-Type： 大多数端点使用 application/json；POST /api/v1/events 使用 application/cloudevents+json

---

概念

Meter (aggregates events) → Feature (metered entitlement) → Plan (limits + pricing)
                                                                    ↓
Customer (subject keys) ←→ Subscription (customer + plan = active entitlements)
                                    ↓
                              Billing Profile → Invoices (via Stripe/Sandbox/Custom App)

• Meter： 事件的聚合规则（COUNT、SUM 等）。事件通过与 eventType 匹配的 type 引用 Meter。
• Feature： 关联 Meter 或布尔值；用于计划费率卡中的配额和超额用量。
• Plan： 包含阶段和费率卡。与 Features 和 Addons 一同属于 Product Catalog。
• Addon： 模块化费率卡套餐，可附加到计划或订阅。
• Customer： 包含 usageAttribution.subjectKeys；事件的 subject 必须与之匹配，用量才能归属于该客户。
• Subscription： 将客户关联到计划；有效订阅会授予权益。
• Entitlement： 客户对某项功能的访问权限，并带有用量跟踪和限制。
• Grant： 针对某项权益的一次性额度或用量分配。
• Notification： 达到权益阈值时触发的自动告警。
• App： 账单服务提供商集成（Stripe、Sandbox、Custom Invoicing）。

---

1. 事件

接收： POST /api/v1/events | Content-Type： application/cloudevents+json

{
  "specversion": "1.0",
  "id": "unique-event-id",
  "type": "api_request",
  "source": "my-app",
  "subject": "user_abc123",
  "time": "2026-02-14T12:00:00Z",
  "data": { "value": 1, "path": "/v1/events", "method": "GET" }
}

字段	必填	说明
type	是	必须与计量器的 eventType 匹配
subject	是	必须与客户的 usageAttribution.subjectKeys 匹配
source	是	标识产生事件的系统
id	是	幂等键（24 小时内去重）
time	建议填写	ISO 8601 时间戳
data	建议填写	任意载荷；计量器使用 $.path 进行 groupBy

列出事件： GET /api/v1/events?from=...&to=...&subject=...&hasError=...

---

2. 计量器

操作	方法	路径
列出	GET	/api/v1/meters
创建	POST	/api/v1/meters
获取	GET	/api/v1/meters/{meterIdOrSlug}
更新	PUT	/api/v1/meters/{meterIdOrSlug}
删除	DELETE	/api/v1/meters/{meterIdOrSlug}
查询用量	GET	/api/v1/meters/{meterIdOrSlug}/query?subject=...&from=...&to=...&windowSize=HOUR
查询（POST）	POST	/api/v1/meters/{meterIdOrSlug}/query
分组值	GET	/api/v1/meters/{meterIdOrSlug}/group-by/{groupBy}/values
列出主体	GET	/api/v1/meters/{meterIdOrSlug}/subjects

聚合类型： COUNT、SUM、AVG、MIN、MAX、UNIQUE_COUNT

窗口大小： MINUTE、HOUR、DAY、MONTH

---

3. 产品目录

套餐、功能和附加项都位于此标签下。有关版本生命周期、费率卡和详细示例，请参阅 references/product-catalog.md。

功能

操作	方法	路径
列出	GET	/api/v1/features
创建	POST	/api/v1/features
获取	GET	/api/v1/features/{featureId}
删除	DELETE	/api/v1/features/{featureId}

套餐

操作	方法	路径
列出	GET	/api/v1/plans
创建	POST	/api/v1/plans
获取	GET	/api/v1/plans/{planIdOrKey}
更新	PUT	/api/v1/plans/{planIdOrKey}
删除	DELETE	/api/v1/plans/{planIdOrKey}
创建下一版本	POST	/api/v1/plans/{planIdOrKey}/next
发布	POST	/api/v1/plans/{planIdOrKey}/publish
归档	POST	/api/v1/plans/{planIdOrKey}/archive
套餐附加项	CRUD	/api/v1/plans/{planIdOrKey}/addons/...

附加项

操作	方法	路径
列出	GET	/api/v1/addons
创建	POST	/api/v1/addons
获取	GET	/api/v1/addons/{addonIdOrKey}
更新	PUT	/api/v1/addons/{addonIdOrKey}
删除	DELETE	/api/v1/addons/{addonIdOrKey}
发布	POST	/api/v1/addons/{addonIdOrKey}/publish
归档	POST	/api/v1/addons/{addonIdOrKey}/archive

重要： 套餐和附加项的键必须使用 snake_case（^[a-z0-9]+(?:_[a-z0-9]+)*$）。费率卡的 upToAmount 必须是字符串。创建订阅时使用 plan: { "key": "plan_key" }，而不是直接使用 planId。套餐遵循草稿 -> 已发布 -> 已归档的生命周期。

---

4. 客户

操作	方法	路径
列出	GET	/api/v1/customers?page=...&pageSize=...&subject=...&planKey=...
创建	POST	/api/v1/customers
获取	GET	/api/v1/customers/{customerIdOrKey}
删除	DELETE	/api/v1/customers/{id}
获取访问权限	GET	/api/v1/customers/{id}/access
订阅	GET	/api/v1/customers/{id}/subscriptions
权益值	GET	/api/v1/customers/{id}/entitlements/{featureKey}/value
Stripe 数据	GET/PUT	/api/v1/customers/{id}/stripe
Stripe 门户	POST	/api/v1/customers/{id}/stripe/portal
应用数据	GET/PUT/DELETE	/api/v1/customers/{id}/apps/{appIdOrType}

注意： 如果客户有有效订阅或尚未结清的发票，DELETE 会返回 409。客户删除流程请参阅 references/billing.md。

---

5. 订阅

操作	方法	路径
创建	POST	/api/v1/subscriptions
获取	GET	/api/v1/subscriptions/{id}
编辑	PATCH	/api/v1/subscriptions/{id}
删除	DELETE	/api/v1/subscriptions/{id}
取消	POST	/api/v1/subscriptions/{id}/cancel
更改计划	POST	/api/v1/subscriptions/{id}/change
迁移	POST	/api/v1/subscriptions/{id}/migrate
恢复	POST	/api/v1/subscriptions/{id}/restore
取消计划取消	POST	/api/v1/subscriptions/{id}/unschedule-cancelation
订阅附加项	GET/POST	/api/v1/subscriptions/{id}/addons

订阅自定义与迁移

关于完整的 PATCH customizations 架构（add_item / remove_item）、stretch_phase 操作、订阅状态允许操作矩阵，以及旧版计划版本迁移模式，请参阅订阅深入解析。

---

6. 权益

操作	方法	路径
列出全部	GET	/api/v1/entitlements
按 ID 获取	GET	/api/v1/entitlements/{id}
每位客户的值	GET	/api/v1/customers/{id}/entitlements/{featureKey}/value
历史记录	GET	/api/v1/subjects/{subjectIdOrKey}/entitlements/{idOrKey}/history
重置用量	POST	/api/v1/subjects/{subjectIdOrKey}/entitlements/{id}/reset
覆盖	PUT	/api/v1/subjects/{subjectIdOrKey}/entitlements/{idOrKey}/override
授予	POST/GET/DELETE	/api/v1/subjects/.../entitlements/.../grants, /api/v1/grants/...

---

7. 计费

有关发票生命周期、删除客户流程和费率卡架构，请参阅 references/billing.md。

资源	操作	基础路径
配置文件	列出、创建、获取、更新、删除	/api/v1/billing/profiles
客户覆盖项	列出、插入或更新、获取、删除	/api/v1/billing/profiles/{id}/customer-overrides
发票	列出、获取、更新、删除、模拟	/api/v1/billing/invoices
发票操作	推进、批准、重试、作废、快照、重新计算税费	POST on /api/v1/billing/invoices/{id}/{action}
待处理明细行	创建、开具发票	/api/v1/billing/customers/{id}/invoices/pending-lines

发票生命周期： gathering → draft → issuing → issued → (paid | void | uncollectible)

---

8. 通知

有关渠道、规则和事件详情，请参阅 references/notifications.md。

资源	操作	基础路径
渠道	列出、创建、获取、更新、删除	/api/v1/notification/channels
规则	列出、创建、获取、更新、删除、测试	/api/v1/notification/rules
事件	列出、获取、重新发送	/api/v1/notification/events

注意： 通过 API 创建渠道仅限 Cloud（由 Svix 支持）。可自托管版本使用 YAML 配置。

---

9. 应用

操作	方法	路径
列出应用	GET	/api/v1/apps
获取应用	GET	/api/v1/apps/{id}
更新应用	PUT	/api/v1/apps/{id}
卸载	DELETE	/api/v1/apps/{id}

应用：Stripe

操作	方法	路径
更新 Stripe 密钥	PUT	/api/v1/apps/{id}/stripe/api-key
Stripe webhook	POST	/api/v1/apps/{id}/stripe/webhook
结账会话	POST	/api/v1/stripe/checkout/sessions

应用：自定义开票

操作	方法	路径
同步草稿	POST	/api/v1/apps/{id}/custom-invoicing/draft-synchronized
同步开具中状态	POST	/api/v1/apps/{id}/custom-invoicing/issuing-synchronized
更新付款状态	POST	/api/v1/apps/{id}/custom-invoicing/update-payment-status

Marketplace

操作	方法	路径
列出商品	GET	/api/v1/marketplace/listings
获取商品	GET	/api/v1/marketplace/listings/{type}
安装（通用）	POST	/api/v1/marketplace/listings/{type}/install
安装（API 密钥）	POST	/api/v1/marketplace/listings/{type}/install/apikey
安装（OAuth2 URL）	GET	/api/v1/marketplace/listings/{type}/install/oauth2
安装（OAuth2 授权）	POST	/api/v1/marketplace/listings/{type}/install/oauth2/authorize

---

10. 门户

操作	方法	路径
创建令牌	POST	/api/v1/portal/tokens
列出令牌	GET	/api/v1/portal/tokens
使令牌失效	POST	/api/v1/portal/tokens/invalidate
查询计量器	GET	/api/v1/portal/meters/{meterSlug}/query

---

11. 查询信息

操作	方法	路径
列出货币	GET	/api/v1/currencies
获取进度	GET	/api/v1/progress

---

12. 调试

操作	方法	路径
获取指标	GET	/api/v1/debug/metrics

---

13. Subjects（已弃用）

请改用 Customers，并使用 usageAttribution.subjectKeys。

操作	方法	路径
列出	GET	/api/v1/subjects
创建或更新	POST	/api/v1/subjects
获取	GET	/api/v1/subjects/{subjectIdOrKey}
删除	DELETE	/api/v1/subjects/{subjectIdOrKey}

---

常见问题与错误

症状	原因	修复方法
DELETE customer 返回 409	存在有效订阅或未结清的发票	先取消订阅，再作废或删除发票
400 "single draft version"	存在重复的计划草稿	如果计划键已存在，则跳过创建
400 "only Plans in [draft scheduled] can be published"	计划已处于活动状态	符合预期 — 跳过发布
POST /notification/channels 返回 500	可自托管版本：尚未实现	本地环境使用 YAML 配置；仅 Cloud 支持 API
PATCH invoice 返回 405	不支持 PATCH	使用 POST 子路径：/advance、/approve、/void
未归属用量	Subject 不匹配	事件的 subject 必须与 usageAttribution.subjectKeys 匹配
未找到计划	键格式错误	使用 snake_case：pro、pro_plus
事件未计量	类型不匹配	事件的 type 必须与计量器的 eventType 相同
未对超额用量计费	阶梯格式错误	upToAmount 必须为字符串；同时包含 flatPrice 和 unitPrice
ID 格式类似 01G65Z...	ULID 格式	标准格式；正则表达式：^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$

---

自托管故障排查：Railway/Kafka

请参阅自托管故障排查，了解“事件未计量”故障模式（Kafka 卷、主题配置、重启顺序）以及 sink-worker 分区不稳定问题。

---

参考资料

第一方文档

• OpenMeter API 参考 — 官方 API 文档
• OpenMeter GitHub — 源代码和示例
• CloudEvents 规范 — 事件格式规范
• OpenMeter Cloud — 托管服务

SDK

• Node.js SDK — 官方 Node.js 客户端
• Python SDK — 官方 Python 客户端
• Go SDK — 官方 Go 客户端

相关技能

• tl-openmeter-local-dev — 本地开发环境设置
• tl-openmeter-api-mcp-server — 用于 Cursor 的 MCP 服务

参考

完整的 OpenAPI 3.0 规范已随附于 assets/openapi-spec.json。请求/响应架构、查询参数和错误代码均以此为准。