tl-openmeter-api 是一个面向 OpenMeter REST API 的项目无关参考技能，用于用量计量、计费与权益管理。它按 OpenAPI 3.0 规范中的官方 API 标签组织内容，便于按功能域快速定位端点。
用途 该技能用于回答与 OpenMeter API 相关的开发与调试问题，例如：如何向 OpenMeter 摄取事件、如何创建带订阅的客户、如何查询某个计量器的用量、如何设置阈值告警的通知规则、如何管理计费发票、如何安装 Stripe 市场应用，以及调试计量、计费或订阅生命周期中的问题。
主要能力 技能覆盖 OpenMeter API 的 15 个官方标签：Apps（应用集成管理）、App: Custom Invoicing（第三方开票与支付系统对接）、App: Stripe（Stripe 计费支持）、Billing（计费配置、发票、客户覆盖、待处理行）、Customers（客户生命周期、应用数据、Stripe 关联、权益值）、Debug（Prometheus 格式内部指标）、Entitlements（用量限制、配额定价、功能访问）、Events（CloudEvents 摄取与列表）、Lookup Information（货币等静态数据）、Meters（聚合规则、用量查询、分组）、Notifications（阈值告警的渠道、规则、事件）、Portal（通过受限令牌的面向消费者的用量仪表盘）、Product Catalog（计划、功能、附加项的版本化、费率卡、发布生命周期）、Subjects（已弃用，建议改用 Customers 的 usageAttribution.subjectKeys）、Subscriptions（客户计划分配、取消、变更、迁移、恢复）。
技能还提供多份参考文档：references/REFERENCE.md 为按官方标签整理的完整端点表；references/billing.md 说明发票生命周期、客户删除流程与费率卡；references/notifications.md 说明渠道、规则、事件与测试；references/product-catalog.md 说明计划、功能、附加项的版本化、费率卡与发布生命周期；assets/openapi-spec.json 为完整的 OpenAPI 3.0 规范，作为请求/响应模式、查询参数与错误码的事实来源。
使用方式 基础 URL 为 OPENMETER_URL（例如本地 http://localhost:8888 或已部署的 URL）。认证使用 Authorization: Bearer <OPENMETER_API_KEY>，本地自托管通常无需认证。多数端点使用 Content-Type: application/json；POST /api/v1/events 使用 application/cloudevents+json。
核心概念链路为：Meter（聚合事件）→ Feature（计量型权益）→ Plan（限制与定价）；Customer（subject keys）↔ Subscription（客户 + 计划 = 生效权益）；Billing Profile → Invoices（通过 Stripe/Sandbox/Custom App）。事件摄取时，type 必须匹配计量器的 eventType，subject 必须匹配客户的 usageAttribution.subjectKeys，id 为幂等键（24 小时内去重）。
适用场景 适用于需要以 OpenMeter 构建用量计量与计费体系的开发、集成与运维场景，包括事件摄取、计量查询、产品目录管理、客户与订阅管理、权益与授权、发票与计费、通知告警、应用与市场集成、门户令牌等。
限制 技能本身为 API 参考，不包含本地开发环境搭建（由 tl-openmeter-local-dev 覆盖）或 MCP 服务器（由 tl-openmeter-api-mcp-server 覆盖）。通知渠道的 API 创建仅限 Cloud（由 Svix 支持），自托管需使用 YAML 配置。Subjects 标签已弃用。部分端点存在已知限制，例如 PATCH 发票不支持，需使用 POST 子路径；删除客户在存在活跃订阅或未终结发票时返回 409。具体收费、价格与平台支持情况暂未提供。