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

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

5. Subscriptions

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

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.