OpenMeter Documentation

OpenMeter is a real-time metering and billing engine designed for AI, agentic, and DevTool monetization. It allows you to track usage, enforce limits, manage subscriptions, and automate invoicing.

Key capabilities include:

• Usage Metering: Ingest events in CloudEvents format and define meters with aggregations like SUM, COUNT, AVG, MIN, and MAX.
• Usage-Based Billing: Generate invoices with support for tiered, graduated, and flat-fee pricing.
• Usage Limits and Entitlements: Enforce quotas and feature flags with real-time balance tracking.
• Product Catalog: Manage plans, add-ons, and subscriptions (including mid-cycle changes and prorating).
• Prepaid Credits: Support for paid or promotional credits with priority-based burn-down.
• Customer Portal: Token-based self-service dashboards for customers to view usage.
• Notifications: Webhook-based alerts for usage thresholds and billing events.
• LLM Cost Tracking: Specialized support for metering AI token usage and model-specific costs.

@openmeter/typespec-go is a TypeSpec emitter that generates the OpenMeter Go SDK from AIP TypeSpec specs. It mirrors the behavior of @openmeter/typespec-typescript but targets Go.

Key Characteristics

• Output Location: The emitter writes to api/v3/client at the repository root. This is a single flat package openmeter that functions as its own nested Go module: github.com/openmeterio/openmeter/api/v3/client.
• Regeneration: The generated files are fully regenerable. Never hand-edit them. If you need changes, modify the emitter or the runtime templates and regenerate. The output cleaner preserves *_test.go and testdata/ files, allowing hand-written wire tests to survive regeneration.
• Data Mapping: The wire format uses snake_case. The Go surface uses PascalCase fields with json:"snake_case" tags. Unlike the TypeScript emitter, there is no casing translation layer.
• Unions: Unions retain their raw JSON for forward-compatible round-tripping.

The OpenMeter JavaScript SDK provides a comprehensive client interface organized into logical namespaces. The API is structured around several core domains:

• Events: Track usage by ingesting single or batch events.
• Meters: Track and aggregate usage data from ingested events.
• Subjects: Manage entities (like users or devices) that consume resources.
• Customers: Manage customer subscription lifecycles, plan assignments, and Stripe integrations.
• Features: Define application capabilities and services.
• Entitlements: Manage subject-based (V1) or customer-based access controls and usage limits.
• Plans & Addons: Manage subscription plans, pricing, and standalone addons.
• Subscriptions: Manage customer subscriptions, including upgrades, downgrades, and cancellations.
• Billing: Comprehensive management of billing profiles, invoices, and customer overrides.
• Apps: Manage integrations and the app marketplace.
• Notifications: Set up automated notifications for usage thresholds via various channels.
• Portal: Manage consumer portal tokens for customer-facing interfaces.
• Info & Debug: Utility endpoints for system information (currencies, operation progress) and debugging (ingestion metrics).

All transactions in the ledger must adhere to strict rules:

• Zero-Sum: Every transaction must sum to zero. Each entry amount must be valid at the posting currency's precision.
• Atomicity: Use CommitGroup to validate the whole input, lock all affected parent accounts, and book the group atomically within the caller's database transaction.
• Routing Rules: Default rules constrain account-type combinations, flow direction, authorization stages, and route compatibility.
• Corrections: Reversals and corrections follow the original entries, preserving charge provenance and using deterministic source order rather than recomputing from current balances.

Note on Idempotency: The historical ledger makes a group atomic but does not deduplicate repeated CommitGroup calls. The initiating domain must ensure retries are safe and persist the returned group reference. Ledger annotations and entry identity are for accounting meaning, not operation idempotency.

The credit collection package converts customer credit and advances into accrued value. Understanding the distinction between timestamps is critical for accurate ledger state:

• BookedAt: The timestamp used for the ledger transactions being written.
• SourceBalanceAsOf: The timestamp used to determine which FBO (Fund Balance Object) sources are available for selection.
• source: A single spendable FBO slice selected by the collector.
• source entry: The specific negative FBO ledger entry created during collection.
• allocation: The billing system's collapsed record of collected credit (may represent multiple source entries).
• advance: Value moved through FBO/accrued before real credit exists to cover it.

Note on Timestamps: BookedAt and SourceBalanceAsOf are intentionally separate. For example, a charge might allocate at T1 (BookedAt), but the source selection logic checks the balance state as of T5 (SourceBalanceAsOf).

The Credit Expiration Breakage package ensures that future credit-expiration ledger entries remain aligned with actual customer credit usage.

In OpenMeter, the ledger is the source of truth for accounting. Breakage records act as an allocation and indexing layer. They allow the system to:

• Find open planned breakage.
• Reopen previously released breakage.
• Project the amount of expired credit visible to the customer.

Key Notation

• FBO(r): Customer credit account route.
• BR(b): Breakage account route used for breakage accounting.
• r.priority: Credit draw-down priority (lower values are consumed first).
• @T: Ledger booked_at timestamp.
• E: Expiration timestamp.
• plan: Pre-booked future breakage for issued expiring credit.
• release: A future entry that reduces planned breakage because credit was used or removed before expiration.
• reopen: A future entry that increases planned breakage because previously used credit became unused.
• breakage impact: The net customer-visible expired amount after netting plans, releases, and reopens.

Routes are part of the accounting identity and carry critical dimensions. Dropping a dimension during translation can merge economically distinct balances.

Route Dimensions

Routes carry: currency, feature restrictions, cost basis, credit priority, receivable authorization status, tax code, and tax behavior.

Key Rules

• Normalization: Routes are normalized before key creation and querying. Feature order is not semantic.
• Filtering: Route.Filter() pins present values, including explicit nil values. An absence of RouteFilter means "do not filter", which is different from filtering for a nil dimension.
• Dimension Ownership:
  • Feature dimensions: Belong only on customer_fbo and customer_receivable routes.
  • Tax dimensions: Belong only on customer_accrued and earnings routes.
• Authorization: Moving between open and authorized receivable routes is a ledger transaction, not an in-place flag update.
• Compatibility: Adding or changing a route dimension is a storage and compatibility change that affects normalization, routing-key versions, and historical data.