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、webhook
tl-openmeter-api-mcp-server	Cursor からローカルの OpenMeter を呼び出す MCP server

使用する場面

• 「OpenMeter にイベントを取り込むにはどうすればよいですか？」
• 「サブスクリプション付きの OpenMeter 顧客を作成する」
• 「メーターの使用量を照会する」
• 「しきい値アラートの通知ルールを設定する」
• 「請求書を管理する」
• 「Stripe マーケットプレイスアプリをインストールする」
• 使用量計測、請求、またはサブスクリプションのライフサイクルのデバッグ

リソース

• 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	顧客へのプラン割り当て、キャンセル、変更、移行、復元

---

ベース URL と認証

• ベース 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 など）です。イベントは type を eventType に一致させることで、メーターを参照します。
• Feature： メーターまたはブール値に関連付けられ、プランのレートカードでクォータや超過分に使用されます。
• 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	推奨	任意のペイロード。メーターでは groupBy に $.path を使用します

イベントの一覧取得： 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
group-by 値	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 は文字列である必要があります。サブスクリプションの作成には、生の planId ではなく plan: { "key": "plan_key" } を使用します。プランは draft -> published -> archived のライフサイクルに従います。

---

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
請求書の操作	進行、承認、再試行、無効化、スナップショット、税金の再計算	/api/v1/billing/invoices/{id}/{action} に対する POST
保留中の明細	作成、請求書化	/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 ウェブフック	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

マーケットプレイス

操作	メソッド	パス
リスティングを一覧表示	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. サブジェクト（非推奨）

代わりに usageAttribution.subjectKeys を指定して顧客を使用してください。

操作	メソッド	パス
一覧表示	GET	/api/v1/subjects
作成または更新	POST	/api/v1/subjects
取得	GET	/api/v1/subjects/{subjectIdOrKey}
削除	DELETE	/api/v1/subjects/{subjectIdOrKey}

---

注意点とエラー

症状	原因	対処法
顧客の DELETE で 409	有効なサブスクリプション、または最終確定前の請求書が存在する	先にサブスクリプションをキャンセルし、請求書を無効化または削除してください
「single draft version」で 400	プランの下書きが重複している	プランキーが存在する場合は作成をスキップしてください
「only Plans in [draft scheduled] can be published」で 400	プランはすでに有効になっている	想定される動作です。公開をスキップしてください
POST /notification/channels で 500	セルフホスト環境では未実装	ローカルでは YAML 設定を使用してください。API は Cloud 専用です
請求書の PATCH で 405	PATCH はサポートされていない	POST サブパス /advance、/approve、/void を使用してください
使用量が帰属されない	サブジェクトが一致しない	イベントの subject は usageAttribution.subjectKeys と一致する必要があります
プランが見つからない	キーの形式が間違っている	スネークケースを使用してください：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 に同梱されています。リクエスト／レスポンスのスキーマ、クエリパラメーター、エラーコードの正しい情報源として使用してください。