tl-openmeter-api（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

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

PATCH Subscription Customizations

The PATCH /api/v1/subscriptions/{id} endpoint supports a customizations array for modifying subscription items without changing plans. This is useful for admin operations like adding bonus quota.

Request body:

{
  "customizations": [
    {
      "op": "add_item",
      "path": "/phases/0/items/{featureKey}",
      "value": {
        "createInput": {
          "type": "boolean" | "static" | "metered",
          "issueAfterReset": 55000,
          "isSoftLimit": false
        }
      }
    }
  ]
}

Use cases:

• Add quota bonus: Increase issueAfterReset to give extra API calls for the current period
• Revert quota: Reset issueAfterReset to plan base value at period end

Key fields:

Response includes:

• items[].entitlement.currentUsagePeriod — Start/end of current billing period
• items[].entitlement.issueAfterReset — Updated quota value

Verified behavior: When issueAfterReset is modified via PATCH, the change is immediately reflected in totalAvailableGrantAmount balance without requiring a period reset.

stretch_phase Operation

The stretch_phase operation extends a subscription phase duration without affecting quota periods. Useful for trial extensions.

Request body:

{
  "customizations": [
    {
      "op": "stretch_phase",
      "phaseKey": "trial",
      "extendBy": "P7D"
    }
  ]
}

Critical: Phase key must match exactly. The phaseKey must match the subscription's actual phase key:

# Check subscription's phase keys first
curl http://localhost:8888/api/v1/subscriptions/{id} | jq '.phases[].key'

Common pitfall: If you update your plan to have different phase keys (e.g., changing from "standard" to "trial"), existing subscriptions retain their original phase keys. The stretch_phase operation will fail with a 400 error if the phase key doesn't exist.

Subscription State Limitations

Key insight: Inactive subscriptions (e.g., ended trials) cannot be modified. To "reactivate" an expired trial, create a new subscription on the current plan version.

Legacy Subscription Migration Pattern

When plan versions change (e.g., adding new phases), existing subscriptions are NOT automatically migrated. For admin tools that modify subscriptions:

const omStatus = await getSubscriptionStatus(subscriptionId);

if (omStatus.status === "inactive" || omStatus.phaseKey !== expectedPhaseKey) {
  // Create new subscription on current plan version
  const newSub = await createSubscription(customerId, planKey);
  // Update local DB with new OpenMeter subscription ID
} else {
  // Use normal modification (stretch_phase, add_item, etc.)
  await patchSubscription(subscriptionId, customizations);
}

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

Events Not Metering (0 Usage, Empty /api/v1/events)

Root Cause: Kafka has no persistent volume. Topics are lost on every Kafka restart.

Symptoms:

• OpenMeter logs: kafka delivery failed: Broker: Unknown topic or partition
• Sink worker logs: no topics found to be subscribed to or partitions=[]
• ClickHouse has 0 tables
• /api/v1/events returns []

Architecture:

Event → OpenMeter API → Kafka → Sink Worker → ClickHouse → Meters

If any link breaks, events don't meter.

Fix:

1. Add Kafka volume at /var/lib/kafka/data

- Railway: Service → Settings → Volumes → Add - For Confluent images: Set RAILWAY_RUN_UID=0 for volume permissions

1. Provision topics explicitly (if KAFKA_AUTO_CREATE_TOPICS_ENABLE=false): om_default_events (namespace events - sink worker consumes) om_sys.api_events om_sys.ingest_events
2. Restart OpenMeter + sink-worker after Kafka restarts to refresh metadata
3. Verify:

- Restart Kafka twice → topics persist - Send test event → appears in /api/v1/events

Kafka Environment Variables (Railway):

KAFKA_AUTO_CREATE_TOPICS_ENABLE=true  # Or provision topics explicitly
KAFKA_LOG_DIRS=/var/lib/kafka/data/logs-v2  # Use subdirectory if cluster ID conflicts
RAILWAY_RUN_UID=0  # Confluent images need root for volume permissions

Sink Worker Partition Instability

Symptom: Sink worker gets partition assignment, loses it within seconds.

Cause: Multiple sink-worker instances competing for single partition (Railway rolling deploys).

Fix: Ensure only 1 sink-worker instance runs. Check Kafka logs for "group... with N members" where N > 1.

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.