tl-openmeter-api

OpenMeter API

Project-agnostic reference for the OpenMeter REST API. Organized by the official API tags from the OpenAPI 3.0 spec.

Suite

Skill	Purpose
tl-openmeter-api	This skill: REST API reference
tl-openmeter-local-dev	Local dev setup: Docker, ngrok, Stripe App, webhooks
tl-openmeter-api-mcp-server	MCP server for calling local OpenMeter from Cursor

When to Use

"How do I ingest events into OpenMeter?"
"Create an OpenMeter customer with subscription"
"Query usage for a meter"
"Set up notification rules for threshold alerts"
"Manage billing invoices"
"Install the Stripe marketplace app"
Debugging metering, billing, or subscription lifecycle

Resources

references/REFERENCE.md — Complete endpoint table by official tag
references/billing.md — Invoice lifecycle, customer delete flow, rate cards
references/notifications.md — Channels, rules, events, testing
references/product-catalog.md — Plans, features, addons: versioning, rate cards, publish lifecycle
assets/openapi-spec.json — Full OpenAPI 3.0 spec (source of truth)

Official API Tags

The OpenMeter API organizes endpoints into these 15 tags:

#	Tag	Description
1	Apps	Manage app integrations (list, get, update, uninstall)
2	App: Custom Invoicing	Interface third-party invoicing and payment systems
3	App: Stripe	Stripe billing support (API key, webhook, checkout)
4	Billing	Billing profiles, invoices, customer overrides, pending lines
5	Customers	Customer lifecycle, app data, Stripe linking, entitlement values
6	Debug	Internal metrics (Prometheus format)
7	Entitlements	Usage limits, quota-based pricing, feature access
8	Events	CloudEvents ingestion and listing
9	Lookup Information	Static data (currencies, progress)
10	Meters	Aggregation rules, usage queries, group-by
11	Notifications	Channels, rules, events for threshold alerts
12	Portal	Consumer-facing usage dashboards via scoped tokens
13	Product Catalog	Plans, features, addons (versioning, rate cards, publish lifecycle)
14	Subjects	Deprecated — use Customers with `usageAttribution.subjectKeys`
15	Subscriptions	Customer plan assignments, cancel, change, migrate, restore

Base URL and Auth

Base URL: OPENMETER_URL (e.g. http://localhost:8888 for local, or your deployed URL)
Auth: Authorization: Bearer <OPENMETER_API_KEY>. Local self-hosted often runs unauthenticated.
Content-Type: application/json for most endpoints; application/cloudevents+json for POST /api/v1/events

Concepts

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: Aggregation rule for events (COUNT, SUM, etc.). Events reference a meter via type matching eventType.
Feature: Tied to a meter or boolean; used in plan rate cards for quotas and overage.
Plan: Contains phases and rate cards. Part of the Product Catalog alongside Features and Addons.
Addon: Modular rate card bundle, attachable to plans or subscriptions.
Customer: Has usageAttribution.subjectKeys; event subject must match for usage to attach.
Subscription: Links customer to plan; active subscription grants entitlements.
Entitlement: Per-customer access to a feature with usage tracking and limits.
Grant: One-time credit or usage allocation against an entitlement.
Notification: Automated alert when entitlement thresholds are reached.
App: Billing provider integration (Stripe, Sandbox, Custom Invoicing).

1. Events

Ingest: 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" }
}

Field	Required	Notes
`type`	Yes	Must match meter's `eventType`
`subject`	Yes	Must match customer's `usageAttribution.subjectKeys`
`source`	Yes	Identifies the producing system
`id`	Yes	Idempotency key (deduplication within 24h)
`time`	Recommended	ISO 8601 timestamp
`data`	Recommended	Arbitrary payload; meters use `$.path` for groupBy

List events: GET /api/v1/events?from=...&to=...&subject=...&hasError=...

2. Meters

Operation	Method	Path
List	GET	`/api/v1/meters`
Create	POST	`/api/v1/meters`
Get	GET	`/api/v1/meters/{meterIdOrSlug}`
Update	PUT	`/api/v1/meters/{meterIdOrSlug}`
Delete	DELETE	`/api/v1/meters/{meterIdOrSlug}`
Query usage	GET	`/api/v1/meters/{meterIdOrSlug}/query?subject=...&from=...&to=...&windowSize=HOUR`
Query (POST)	POST	`/api/v1/meters/{meterIdOrSlug}/query`
Group-by values	GET	`/api/v1/meters/{meterIdOrSlug}/group-by/{groupBy}/values`
List subjects	GET	`/api/v1/meters/{meterIdOrSlug}/subjects`

Aggregation types: COUNT, SUM, AVG, MIN, MAX, UNIQUE_COUNT

Window sizes: MINUTE, HOUR, DAY, MONTH

3. Product Catalog

Plans, Features, and Addons all live under this tag. See references/product-catalog.md for versioning lifecycle, rate cards, and detailed examples.

Features

Operation	Method	Path
List	GET	`/api/v1/features`
Create	POST	`/api/v1/features`
Get	GET	`/api/v1/features/{featureId}`
Delete	DELETE	`/api/v1/features/{featureId}`

Plans

Operation	Method	Path
List	GET	`/api/v1/plans`
Create	POST	`/api/v1/plans`
Get	GET	`/api/v1/plans/{planIdOrKey}`
Update	PUT	`/api/v1/plans/{planIdOrKey}`
Delete	DELETE	`/api/v1/plans/{planIdOrKey}`
Next version	POST	`/api/v1/plans/{planIdOrKey}/next`
Publish	POST	`/api/v1/plans/{planIdOrKey}/publish`
Archive	POST	`/api/v1/plans/{planIdOrKey}/archive`
Plan Addons	CRUD	`/api/v1/plans/{planIdOrKey}/addons/...`

Addons

Operation	Method	Path
List	GET	`/api/v1/addons`
Create	POST	`/api/v1/addons`
Get	GET	`/api/v1/addons/{addonIdOrKey}`
Update	PUT	`/api/v1/addons/{addonIdOrKey}`
Delete	DELETE	`/api/v1/addons/{addonIdOrKey}`
Publish	POST	`/api/v1/addons/{addonIdOrKey}/publish`
Archive	POST	`/api/v1/addons/{addonIdOrKey}/archive`

Critical: Plan/addon keys must be snake_case (^[a-z0-9]+(?:_[a-z0-9]+)*$). Rate card upToAmount must be a string. Subscription creation uses plan: { "key": "plan_key" }, not a raw planId. Plans follow a draft -> published -> archived lifecycle.

4. Customers

Operation	Method	Path
List	GET	`/api/v1/customers?page=...&pageSize=...&subject=...&planKey=...`
Create	POST	`/api/v1/customers`
Get	GET	`/api/v1/customers/{customerIdOrKey}`
Delete	DELETE	`/api/v1/customers/{id}`
Get access	GET	`/api/v1/customers/{id}/access`
Subscriptions	GET	`/api/v1/customers/{id}/subscriptions`
Entitlement value	GET	`/api/v1/customers/{id}/entitlements/{featureKey}/value`
Stripe data	GET/PUT	`/api/v1/customers/{id}/stripe`
Stripe portal	POST	`/api/v1/customers/{id}/stripe/portal`
App data	GET/PUT/DELETE	`/api/v1/customers/{id}/apps/{appIdOrType}`

Gotcha: DELETE returns 409 if customer has active subscriptions or non-final invoices. See references/billing.md for the customer delete flow.

5. Subscriptions

Operation	Method	Path
Create	POST	`/api/v1/subscriptions`
Get	GET	`/api/v1/subscriptions/{id}`
Edit	PATCH	`/api/v1/subscriptions/{id}`
Delete	DELETE	`/api/v1/subscriptions/{id}`
Cancel	POST	`/api/v1/subscriptions/{id}/cancel`
Change plan	POST	`/api/v1/subscriptions/{id}/change`
Migrate	POST	`/api/v1/subscriptions/{id}/migrate`
Restore	POST	`/api/v1/subscriptions/{id}/restore`
Unschedule cancel	POST	`/api/v1/subscriptions/{id}/unschedule-cancelation`
Subscription addons	GET/POST	`/api/v1/subscriptions/{id}/addons`

Subscription Customizations and Migration

See Subscriptions Deep Dive for the full PATCH customizations schema (add_item / remove_item), the stretch_phase operation, subscription state allowed-operations matrix, and the legacy plan-version migration pattern.

6. Entitlements

Operation	Method	Path
List all	GET	`/api/v1/entitlements`
Get by id	GET	`/api/v1/entitlements/{id}`
Per-customer value	GET	`/api/v1/customers/{id}/entitlements/{featureKey}/value`
History	GET	`/api/v1/subjects/{subjectIdOrKey}/entitlements/{idOrKey}/history`
Reset usage	POST	`/api/v1/subjects/{subjectIdOrKey}/entitlements/{id}/reset`
Override	PUT	`/api/v1/subjects/{subjectIdOrKey}/entitlements/{idOrKey}/override`
Grants	POST/GET/DELETE	`/api/v1/subjects/.../entitlements/.../grants`, `/api/v1/grants/...`

7. Billing

See references/billing.md for invoice lifecycle, customer delete flow, and rate card schemas.

Resource	Operations	Base Path
Profiles	List, Create, Get, Update, Delete	`/api/v1/billing/profiles`
Customer overrides	List, Upsert, Get, Delete	`/api/v1/billing/profiles/{id}/customer-overrides`
Invoices	List, Get, Update, Delete, Simulate	`/api/v1/billing/invoices`
Invoice actions	Advance, Approve, Retry, Void, Snapshot, Recalculate tax	POST on `/api/v1/billing/invoices/{id}/{action}`
Pending lines	Create, Invoice	`/api/v1/billing/customers/{id}/invoices/pending-lines`

Invoice lifecycle: gathering → draft → issuing → issued → (paid | void | uncollectible)

8. Notifications

See references/notifications.md for channels, rules, and event details.

Resource	Operations	Base Path
Channels	List, Create, Get, Update, Delete	`/api/v1/notification/channels`
Rules	List, Create, Get, Update, Delete, Test	`/api/v1/notification/rules`
Events	List, Get, Resend	`/api/v1/notification/events`

Note: Channel creation via API is Cloud-only (Svix-backed). Self-hosted uses YAML config.

9. Apps

Operation	Method	Path
List apps	GET	`/api/v1/apps`
Get app	GET	`/api/v1/apps/{id}`
Update app	PUT	`/api/v1/apps/{id}`
Uninstall	DELETE	`/api/v1/apps/{id}`

App: Stripe

Operation	Method	Path
Update Stripe key	PUT	`/api/v1/apps/{id}/stripe/api-key`
Stripe webhook	POST	`/api/v1/apps/{id}/stripe/webhook`
Checkout session	POST	`/api/v1/stripe/checkout/sessions`

App: Custom Invoicing

Operation	Method	Path
Draft synced	POST	`/api/v1/apps/{id}/custom-invoicing/draft-synchronized`
Issuing synced	POST	`/api/v1/apps/{id}/custom-invoicing/issuing-synchronized`
Update payment	POST	`/api/v1/apps/{id}/custom-invoicing/update-payment-status`

Marketplace

Operation	Method	Path
List listings	GET	`/api/v1/marketplace/listings`
Get listing	GET	`/api/v1/marketplace/listings/{type}`
Install (generic)	POST	`/api/v1/marketplace/listings/{type}/install`
Install (API key)	POST	`/api/v1/marketplace/listings/{type}/install/apikey`
Install (OAuth2 URL)	GET	`/api/v1/marketplace/listings/{type}/install/oauth2`
Install (OAuth2 auth)	POST	`/api/v1/marketplace/listings/{type}/install/oauth2/authorize`

10. Portal

Operation	Method	Path
Create token	POST	`/api/v1/portal/tokens`
List tokens	GET	`/api/v1/portal/tokens`
Invalidate tokens	POST	`/api/v1/portal/tokens/invalidate`
Query meter	GET	`/api/v1/portal/meters/{meterSlug}/query`

11. Lookup Information

Operation	Method	Path
List currencies	GET	`/api/v1/currencies`
Get progress	GET	`/api/v1/progress`

12. Debug

Operation	Method	Path
Get metrics	GET	`/api/v1/debug/metrics`

13. Subjects (Deprecated)

Use Customers with usageAttribution.subjectKeys instead.

Operation	Method	Path
List	GET	`/api/v1/subjects`
Upsert	POST	`/api/v1/subjects`
Get	GET	`/api/v1/subjects/{subjectIdOrKey}`
Delete	DELETE	`/api/v1/subjects/{subjectIdOrKey}`

Gotchas and Errors

Symptom	Cause	Fix
409 on DELETE customer	Active subscriptions or non-final invoices	Cancel subs, void/delete invoices first
400 "single draft version"	Duplicate plan draft	Skip creation if plan key exists
400 "only Plans in [draft scheduled] can be published"	Plan already active	Expected — skip publish
500 on POST /notification/channels	Self-hosted: not implemented	Use YAML config for local; API for Cloud only
405 on PATCH invoice	PATCH not supported	Use POST subpaths: `/advance`, `/approve`, `/void`
Usage not attributed	Subject mismatch	Event `subject` must match `usageAttribution.subjectKeys`
Plan not found	Wrong key format	Use snake_case: `pro`, `pro_plus`
Event not metered	Type mismatch	Event `type` must equal meter's `eventType`
Overage not billed	Tier format	`upToAmount` must be string; include both `flatPrice` and `unitPrice`
IDs look like `01G65Z...`	ULID format	Standard; regex: `^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$`

Self-Hosted Troubleshooting: Railway/Kafka

See Self-Hosted Troubleshooting for the "events not metering" failure mode (Kafka volumes, topic provisioning, restart sequence) and sink-worker partition instability.

References

First-Party Documentation

OpenMeter API Reference — Official API documentation
OpenMeter GitHub — Source code and examples
CloudEvents Specification — Event format specification
OpenMeter Cloud — Managed service

SDKs

Node.js SDK — Official Node.js client
Python SDK — Official Python client
Go SDK — Official Go client

Related Skills

tl-openmeter-local-dev — Local development setup
tl-openmeter-api-mcp-server — MCP server for Cursor

Reference

The full OpenAPI 3.0 spec is bundled at assets/openapi-spec.json. Use it as the source of truth for request/response schemas, query parameters, and error codes.