tl-openmeter-api

<!-- Copyright (c) 2026 Todd Levy. Licensed under MIT. SPDX-License-Identifier: MIT -->

OpenMeter API

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

Suite

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:

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

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

2. Meters

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

Plans

Addons

Critical: Plan/addon keys must be snakecase (`^[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

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

5. Subscriptions

Subscription Customizations and Migration

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

6. Entitlements

7. Billing

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

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

8. Notifications

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

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

9. Apps

App: Stripe

App: Custom Invoicing

Marketplace

10. Portal

11. Lookup Information

12. Debug

13. Subjects (Deprecated)

Use Customers with usageAttribution.subjectKeys instead.

Gotchas and Errors

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.