OpenMeter JavaScript SDK

Install

npm install --save @openmeter/sdk

Configuration for accessing the OpenMeter API

To use the OpenMeter SDK on your backend, you need to configure baseUrl and apiKey for OpenMeter Cloud:

import { OpenMeter } from '@openmeter/sdk'

const openmeter = new OpenMeter({
  baseUrl: 'https://openmeter.cloud',
  apiKey: 'om_...',
})

Configuration for accessing the OpenMeter Portal API

To use the OpenMeter Portal SDK on your frontend, you need to configure it use a portal token in your configuration:

import { OpenMeter } from '@openmeter/sdk/portal'

const openmeter = new OpenMeter({
  baseUrl: 'https://openmeter.cloud',
  portalToken: 'om_portal_...',
})

Configuration for accessing the OpenMeter React SDK

To use the OpenMeter React SDK for the portal API, you need to configure a Portal Client and a React Context:

import {
  OpenMeter,
  OpenMeterProvider,
  useOpenMeter,
} from '@openmeter/sdk/react'

function App() {
  // get portal token from your backend
  const openmeter = new OpenMeter({
    baseUrl: 'https://openmeter.cloud',
    portalToken,
  })

  return (
    <OpenMeterProvider value={openmeter}>
      <UsageComponent />
      {/* ... */}
    </OpenMeterProvider>
  )
}

function UsageComponent() {
  // get openmeter client from context
  const openmeter = useOpenMeter()

  // ...
}

Ingest usage events

// Ingest a single AI token usage event
await openmeter.events.ingest({
  type: 'ai-tokens',
  subject: 'customer-acme-corp',
  id: 'evt_01234567', // optional: auto-generated if not provided
  source: 'llm-api-gateway', // optional: defaults to '@openmeter/sdk'
  time: new Date(), // optional: defaults to current time
  data: {
    model: 'gpt-4',
    type: 'input',
    tokens: 1250,
  },
})

// Ingest multiple events in a batch for better performance
await openmeter.events.ingest([
  {
    type: 'ai-tokens',
    subject: 'customer-acme-corp',
    data: { model: 'gpt-4', type: 'input', tokens: 850 },
  },
  {
    type: 'ai-tokens',
    subject: 'customer-acme-corp',
    data: { model: 'gpt-4', type: 'output', tokens: 850 },
  },
])

Client API Reference

The OpenMeter SDK provides a comprehensive client interface organized into logical groups. Below is a complete reference of all available methods.

Overview

| Namespace | Resource | Operation | Method | Description | |-----------|----------|-----------|--------|-------------| | Events | | | | Track usage by ingesting events | | | Events | Create | openmeter.events.ingest(events) | Ingest a single event or batch of events | | | Events | Read | openmeter.events.list(params?) | List ingested events with advanced filtering | | | Events | Read | openmeter.events.listV2(params?) | List ingested events with advanced filtering (V2) | | Meters | | | | Track and aggregate usage data from events | | | Meters | Create | openmeter.meters.create(meter) | Create a new meter | | | Meters | Read | openmeter.meters.get(idOrSlug) | Get a meter by ID or slug | | | Meters | Read | openmeter.meters.list() | List all meters | | | Meters | Read | openmeter.meters.query(idOrSlug, query?) | Query usage data | | | Meters | Update | openmeter.meters.update(idOrSlug, meter) | Update a meter by ID or slug | | | Meters | Delete | openmeter.meters.delete(idOrSlug) | Delete a meter by ID or slug | | Subjects | | | | Manage entities that consume resources | | | Subjects | Create | openmeter.subjects.upsert(subjects) | Create or update one or multiple subjects | | | Subjects | Read | openmeter.subjects.get(idOrKey) | Get a subject by ID or key | | | Subjects | Read | openmeter.subjects.list() | List all subjects | | | Subjects | Delete | openmeter.subjects.delete(idOrKey) | Delete a subject by ID or key | | Customers | | | | Manage customer subscription lifecycles and plan assignments | | | Customers | Create | openmeter.customers.create(customer) | Create a new customer | | | Customers | Read | openmeter.customers.get(customerIdOrKey) | Get a customer by ID or key | | | Customers | Read | openmeter.customers.list(query?) | List all customers | | | Customers | Read | openmeter.customers.getAccess(customerIdOrKey) | Get customer access information | | | Customers | Read | openmeter.customers.listSubscriptions(customerIdOrKey, query?) | List customer subscriptions | | | Customers | Update | openmeter.customers.update(customerIdOrKey, customer) | Update a customer | | | Customers | Delete | openmeter.customers.delete(customerIdOrKey) | Delete a customer | | | Apps | Update | openmeter.customers.apps.upsert(customerIdOrKey, appData) | Upsert app data | | | Apps | Read | openmeter.customers.apps.list(customerIdOrKey) | List app data | | | Apps | Delete | openmeter.customers.apps.delete(customerIdOrKey, appId) | Delete app data | | | Stripe | Update | openmeter.customers.stripe.upsert(customerIdOrKey, appDataBase) | Upsert Stripe app data | | | Stripe | Read | openmeter.customers.stripe.get(customerIdOrKey) | Get Stripe app data | | | Stripe | Create | openmeter.customers.stripe.createPortalSession(customerIdOrKey, params) | Create a Stripe customer portal session | | | Entitlements V1 | Read | openmeter.customers.entitlementsV1.value(customerIdOrKey, featureKey) | Get entitlement value (V1 API) | | | Entitlements | Read | openmeter.customers.entitlements.list(customerIdOrKey) | List entitlements | | | Entitlements | Create | openmeter.customers.entitlements.create(customerIdOrKey, entitlement) | Create an entitlement | | | Entitlements | Read | openmeter.customers.entitlements.get(customerIdOrKey, featureKeyOrId) | Get an entitlement | | | Entitlements | Delete | openmeter.customers.entitlements.delete(customerIdOrKey, entitlementId) | Delete an entitlement | | | Entitlements | Update | openmeter.customers.entitlements.override(customerIdOrKey, featureKeyOrId, entitlement) | Override an entitlement | | | Entitlements | Read | openmeter.customers.entitlements.value(customerIdOrKey, featureKeyOrId, query?) | Get entitlement value | | | Entitlements | Read | openmeter.customers.entitlements.history(customerIdOrKey, featureKeyOrId, query?) | Get entitlement history | | | Entitlements | Update | openmeter.customers.entitlements.resetUsage(customerIdOrKey, entitlementId, body?) | Reset usage | | | Entitlements | Read | openmeter.customers.entitlements.listGrants(customerIdOrKey, featureKeyOrId, query?) | List grants | | | Entitlements | Create | openmeter.customers.entitlements.createGrant(customerIdOrKey, featureKeyOrId, grant) | Create a grant | | Features | | | | Define application capabilities and services | | | Features | Create | openmeter.features.create(feature) | Create a new feature | | | Features | Read | openmeter.features.get(featureIdOrKey) | Get a feature by ID | | | Features | Read | openmeter.features.list(params?) | List all features | | | Features | Delete | openmeter.features.delete(featureIdOrKey) | Delete a feature by ID | | Entitlements (V1) | | | | Subject-based usage limits and access controls | | | Entitlements | Create | openmeter.entitlementsV1.create(subjectIdOrKey, entitlement) | Create an entitlement for a subject | | | Entitlements | Read | openmeter.entitlementsV1.get(entitlementId) | Get an entitlement by ID | | | Entitlements | Read | openmeter.entitlementsV1.list(query?) | List all entitlements | | | Entitlements | Read | openmeter.entitlementsV1.value(subjectIdOrKey, featureIdOrKey, query?) | Get the value of an entitlement | | | Entitlements | Read | openmeter.entitlementsV1.history(subjectIdOrKey, entitlementIdOrFeatureKey, query?) | Get the history of an entitlement | | | Entitlements | Update | openmeter.entitlementsV1.override(subjectIdOrKey, entitlementIdOrFeatureKey, override) | Override an entitlement | | | Entitlements | Update | openmeter.entitlementsV1.reset(subjectIdOrKey, entitlementIdOrFeatureKey, reset?) | Reset entitlement usage | | | Entitlements | Delete | openmeter.entitlementsV1.delete(subjectIdOrKey, entitlementId) | Delete an entitlement | | | Grants | Create | openmeter.entitlementsV1.grants.create(subjectIdOrKey, entitlementIdOrFeatureKey, grant) | Create a grant for an entitlement | | | Grants | Read | openmeter.entitlementsV1.grants.list(subjectIdOrKey, entitlementIdOrFeatureKey, query?) | List grants for an entitlement | | | Grants | Read | openmeter.entitlementsV1.grants.listAll(query?) | List all grants | | | Grants | Delete | openmeter.entitlementsV1.grants.void(entitlementId, grantId) | Void a grant | | Entitlements | | | | Customer-based entitlements and access controls | | | Entitlements | Read | openmeter.entitlements.list(query?) | List all entitlements (admin purposes) | | | Entitlements | Read | openmeter.entitlements.get(entitlementId) | Get an entitlement by ID | | | Grants | Read | openmeter.entitlements.grants.list(query?) | List all grants (admin purposes) | | | Grants | Delete | openmeter.entitlements.grants.void(grantId) | Void a grant | | Plans | | | | Manage subscription plans and pricing| | | Plans | Create | openmeter.plans.create(plan) | Create a new plan| | | Plans | Read | openmeter.plans.get(planId) | Get a plan by ID| | | Plans | Read | openmeter.plans.list(query?) | List all plans| | | Plans | Update | openmeter.plans.update(planId, plan) | Update a plan| | | Plans | Delete | openmeter.plans.delete(planId) | Delete a plan by ID| | | Plans | Other | openmeter.plans.archive(planId) | Archive a plan| | | Plans | Other | openmeter.plans.publish(planId) | Publish a plan| | | Addons | Read | openmeter.plans.addons.list(planId) | List addons| | | Addons | Create | openmeter.plans.addons.create(planId, addon) | Create an addon| | | Addons | Read | openmeter.plans.addons.get(planId, planAddonId) | Get an addon by ID| | | Addons | Update | openmeter.plans.addons.update(planId, planAddonId, addon) | Update an addon| | | Addons | Delete | openmeter.plans.addons.delete(planId, planAddonId) | Delete an addon by ID| | Addons | | | | Manage standalone addons available across plans| | | Addons | Create | openmeter.addons.create(addon) | Create a new addon| | | Addons | Read | openmeter.addons.get(addonId) | Get an addon by ID| | | Addons | Read | openmeter.addons.list(query?) | List all addons| | | Addons | Update | openmeter.addons.update(addonId, addon) | Update an addon| | | Addons | Delete | openmeter.addons.delete(addonId) | Delete an addon by ID| | | Addons | Other | openmeter.addons.publish(addonId) | Publish an addon| | | Addons | Other | openmeter.addons.archive(addonId) | Archive an addon| | Subscriptions | | | | Manage customer subscriptions| | | Subscriptions | Create | openmeter.subscriptions.create(body) | Create a new subscription| | | Subscriptions | Read | openmeter.subscriptions.get(subscriptionId) | Get a subscription by ID| | | Subscriptions | Update | openmeter.subscriptions.edit(subscriptionId, body) | Edit a subscription| | | Subscriptions | Delete | openmeter.subscriptions.delete(subscriptionId) | Delete a subscription (only scheduled)| | | Subscriptions | Other | openmeter.subscriptions.cancel(subscriptionId, body?) | Cancel a subscription| | | Subscriptions | Other | openmeter.subscriptions.change(subscriptionId, body) | Change a subscription (upgrade/downgrade)| | | Subscriptions | Other | openmeter.subscriptions.migrate(subscriptionId, body) | Migrate to a new plan version| | | Subscriptions | Other | openmeter.subscriptions.unscheduleCancelation(subscriptionId) | Unschedule a subscription cancelation| | Subscription Addons | | | | Manage addons attached to specific subscriptions| | | Subscription Addons | Create | openmeter.subscriptionAddons.create(subscriptionId, body) | Create a new subscription addon| | | Subscription Addons | Read | openmeter.subscriptionAddons.get(subscriptionId, subscriptionAddonId) | Get a subscription addon by ID| | | Subscription Addons | Read | openmeter.subscriptionAddons.list(subscriptionId) | List all addons of a subscription| | | Subscription Addons | Update | openmeter.subscriptionAddons.update(subscriptionId, subscriptionAddonId, body) | Update a subscription addon| | Billing | | | | Comprehensive billing management (profiles, invoices, overrides)| | | Profiles | Create | openmeter.billing.profiles.create(profile) | Create a billing profile| | | Profiles | Read | openmeter.billing.profiles.get(id) | Get a billing profile by ID| | | Profiles | Read | openmeter.billing.profiles.list(query?) | List billing profiles| | | Profiles | Update | openmeter.billing.profiles.update(id, profile) | Update a billing profile| | | Profiles | Delete | openmeter.billing.profiles.delete(id) | Delete a billing profile| | | Invoices | Read | openmeter.billing.invoices.list(query?) | List invoices| | | Invoices | Read | openmeter.billing.invoices.get(id, query?) | Get an invoice by ID| | | Invoices | Update | openmeter.billing.invoices.update(id, invoice) | Update an invoice (draft or earlier)| | | Invoices | Delete | openmeter.billing.invoices.delete(id) | Delete an invoice (draft or earlier)| | | Invoices | Other | openmeter.billing.invoices.advance(id) | Advance invoice to next status| | | Invoices | Other | openmeter.billing.invoices.approve(id) | Approve an invoice (sends to customer)| | | Invoices | Other | openmeter.billing.invoices.retry(id, body?) | Retry advancing after failure| | | Invoices | Other | openmeter.billing.invoices.void(id) | Void an invoice| | | Invoices | Other | openmeter.billing.invoices.recalculateTax(id) | Recalculate invoice tax amounts| | | Invoices | Other | openmeter.billing.invoices.simulate(customerId, query?) | Simulate an invoice for a customer| | | Invoices | Create | openmeter.billing.invoices.createLineItems(customerId, body) | Create pending line items| | | Invoices | Create | openmeter.billing.invoices.invoicePendingLines(customerId) | Invoice pending lines| | | Customers | Create | openmeter.billing.customers.createOverride(customerId, body) | Create or update a customer override| | | Customers | Read | openmeter.billing.customers.getOverride(customerId, id) | Get a customer override| | | Customers | Read | openmeter.billing.customers.listOverrides(customerId) | List customer overrides| | | Customers | Delete | openmeter.billing.customers.deleteOverride(customerId, id) | Delete a customer override| | Apps | | | | Manage integrations and app marketplace| | | Apps | Read | openmeter.apps.list(query?) | List installed apps| | | Apps | Read | openmeter.apps.get(id) | Get an app by ID| | | Apps | Update | openmeter.apps.update(id, body) | Update an app| | | Apps | Delete | openmeter.apps.uninstall(id) | Uninstall an app| | | Marketplace | Read | openmeter.apps.marketplace.list(query?) | List available marketplace apps| | | Marketplace | Read | openmeter.apps.marketplace.get(id) | Get marketplace listing details| | | Marketplace | Read | openmeter.apps.marketplace.getOauth2InstallUrl(id, redirectUrl) | Get OAuth2 install URL| | | Marketplace | Other | openmeter.apps.marketplace.authorizeOauth2(id, body) | Authorize OAuth2 code| | | Marketplace | Create | openmeter.apps.marketplace.installWithAPIKey(id, body) | Install app with API key| | | Stripe | Create | openmeter.apps.stripe.createCheckoutSession(body) | Create a Stripe checkout session| | | Stripe | Update | openmeter.apps.stripe.updateApiKey(body) | Update Stripe API key| | | Custom Invoicing | Other | openmeter.apps.customInvoicing.draftSynchronized(body) | Submit draft synchronization results| | | Custom Invoicing | Other | openmeter.apps.customInvoicing.issuingSynchronized(body) | Submit issuing synchronization results| | | Custom Invoicing | Update | openmeter.apps.customInvoicing.updatePaymentStatus(invoiceId, body) | Update payment status| | Notifications | | | | Set up automated notifications for usage thresholds| | | Channels | Create | openmeter.notifications.channels.create(channel) | Create a notification channel| | | Channels | Read | openmeter.notifications.channels.get(channelId) | Get a notification channel by ID| | | Channels | Update | openmeter.notifications.channels.update(channelId, channel) | Update a notification channel| | | Channels | Read | openmeter.notifications.channels.list(query?) | List notification channels| | | Channels | Delete | openmeter.notifications.channels.delete(channelId) | Delete a notification channel| | | Rules | Create | openmeter.notifications.rules.create(rule) | Create a notification rule| | | Rules | Read | openmeter.notifications.rules.get(ruleId) | Get a notification rule by ID| | | Rules | Update | openmeter.notifications.rules.update(ruleId, rule) | Update a notification rule| | | Rules | Read | openmeter.notifications.rules.list(query?) | List notification rules| | | Rules | Delete | openmeter.notifications.rules.delete(ruleId) | Delete a notification rule| | | Events | Read | openmeter.notifications.events.get(eventId) | Get a notification event by ID| | | Events | Read | openmeter.notifications.events.list(query?) | List notification events| | Portal | | | | Manage consumer portal tokens for customer-facing interfaces| | | Portal | Create | openmeter.portal.create(body) | Create a consumer portal token| | | Portal | Read | openmeter.portal.list(query?) | List consumer portal tokens| | | Portal | Other | openmeter.portal.invalidate(query?) | Invalidate consumer portal tokens| | Info | | | | Utility endpoints for system information| | | Info | Read | openmeter.info.listCurrencies() | List all supported currencies| | | Info | Read | openmeter.info.getProgress(id) | Get progress of a long-running operation| | Debug | | | | Debug utilities for monitoring and troubleshooting| | | Debug | Read | openmeter.debug.getMetrics() | Get event ingestion metrics (OpenMetrics format)|