api/v3/client/README.md

OpenMeter Go SDK

Go client for the OpenMeter API — usage metering and billing for AI and DevTool companies. This package is generated from the OpenMeter TypeSpec definitions and ships typed request and response models.

This SDK is a work in progress.

This SDK targets the OpenMeter API v3, a rewrite of the OpenMeter API following AIP (API Improvement Proposal) standardization.

Table of Contents

• Installation
• Initialization
• Usage
• Available Resources and Operations
  • Events
  • Meters
  • Customers
  • Entitlements
  • Subscriptions
  • Apps
  • Billing
  • Invoices
  • Tax
  • Currencies
  • Features
  • LLMCost
  • Plans
  • Addons
  • PlanAddons
  • Defaults
  • Governance
• Error Handling
• Pagination and Streaming

Installation

go get github.com/openmeterio/openmeter/api/v3/client

Initialization

Create a client with a base URL and an API key. The API key is sent as a Bearer token on every request.

package main

import (
    "log"
    "os"

    "github.com/openmeterio/openmeter/api/v3/client"
)

func main() {
    om, err := openmeter.New(
        "https://openmeter.cloud/api/v3",
        openmeter.WithToken(os.Getenv("OPENMETER_API_KEY")),
    )
    if err != nil {
        log.Fatal(err)
    }

    _ = om
}

For region-specific deployments, pass the concrete API base URL for that region to New.

Usage

Every operation is reachable through a namespaced service on the client and returns a typed response plus an error.

package main

import (
    "context"
    "log"
    "os"

    "github.com/openmeterio/openmeter/api/v3/client"
)

func main() {
    om, err := openmeter.New(
        "https://openmeter.cloud/api/v3",
        openmeter.WithToken(os.Getenv("OPENMETER_API_KEY")),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    meter, err := om.Meters.Create(ctx, openmeter.CreateMeterRequest{
        Name:          "Tokens",
        Key:           "tokens",
        Aggregation:   openmeter.MeterAggregationSum,
        EventType:     "request",
        ValueProperty: openmeter.String("$.tokens"),
    })
    if err != nil {
        log.Fatal(err)
    }

    meters, err := om.Meters.List(ctx, openmeter.MeterListParams{})
    if err != nil {
        log.Fatal(err)
    }

    _, _ = meter, meters
}

Operation arguments follow the generated method signature: path parameters come first, then a typed request body when present, then typed query params when present.

Available Resources and Operations

Operations are grouped by resource and exposed as services on the client. The full call path, HTTP route, and a short description are listed below.

Events

Method	HTTP	Description
om.Events.List	GET /openmeter/events	List ingested events.
om.Events.IngestEvent	POST /openmeter/events	Ingests an event or batch of events following the CloudEvents specification.
om.Events.IngestEvents	POST /openmeter/events
om.Events.IngestEventsJSON	POST /openmeter/events

Meters

Method	HTTP	Description
om.Meters.Create	POST /openmeter/meters	Create a meter.
om.Meters.Get	GET /openmeter/meters/{meterId}	Get a meter by ID.
om.Meters.List	GET /openmeter/meters	List meters.
om.Meters.Update	PUT /openmeter/meters/{meterId}	Update a meter.
om.Meters.Delete	DELETE /openmeter/meters/{meterId}	Delete a meter.
om.Meters.Query	POST /openmeter/meters/{meterId}/query	Query a meter for usage. Set Accept: application/json (the default) to get a structured JSON response. Set Accept: text/csv to download the same data as a CSV file suitable for spreadsheets. The CSV columns, in order, are: from, to, [subject,] [customer_id, customer_key, customer_name,] <dimensions...>, value The subject column is emitted only when subject is in the query's group_by_dimensions. The three customer_* columns are emitted together only when customer_id is in the query's group_by_dimensions.
om.Meters.QueryCSV	POST /openmeter/meters/{meterId}/query
om.Meters.QueryCSVStream	POST /openmeter/meters/{meterId}/query	Streaming variant of QueryCSV returning an io.ReadCloser.

Customers

Method	HTTP	Description
om.Customers.Create	POST /openmeter/customers
om.Customers.Get	GET /openmeter/customers/{customerId}
om.Customers.List	GET /openmeter/customers
om.Customers.Upsert	PUT /openmeter/customers/{customerId}
om.Customers.Delete	DELETE /openmeter/customers/{customerId}
om.Customers.Billing.Get	GET /openmeter/customers/{customerId}/billing
om.Customers.Billing.Update	PUT /openmeter/customers/{customerId}/billing
om.Customers.Billing.UpdateAppData	PUT /openmeter/customers/{customerId}/billing/app-data
om.Customers.Billing.CreateStripeCheckoutSession	POST /openmeter/customers/{customerId}/billing/stripe/checkout-sessions	Create a Stripe Checkout Session for the customer. Creates a Checkout Session for collecting payment method information from customers. The session operates in "setup" mode, which collects payment details without charging the customer immediately. The collected payment method can be used for future subscription billing. For hosted checkout sessions, redirect customers to the returned URL. For embedded sessions, use the client_secret to initialize Stripe.js in your application.
om.Customers.Billing.CreateStripePortalSession	POST /openmeter/customers/{customerId}/billing/stripe/portal-sessions	Create Stripe Customer Portal Session. Useful to redirect the customer to the Stripe Customer Portal to manage their payment methods, change their billing address and access their invoice history. Only returns URL if the customer billing profile is linked to a stripe app and customer.
om.Customers.Credits.Grants.Create	POST /openmeter/customers/{customerId}/credits/grants	Create a new credit grant. A credit grant represents an allocation of prepaid credits to a customer.
om.Customers.Credits.Grants.Get	GET /openmeter/customers/{customerId}/credits/grants/{creditGrantId}	Get a credit grant.
om.Customers.Credits.Grants.List	GET /openmeter/customers/{customerId}/credits/grants	List credit grants.
om.Customers.Credits.Grants.Void	POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/void	Void a credit grant, forfeiting the remaining unused balance. Voiding is a forward-looking, irreversible operation. Credits already consumed by usage remain unaffected — only the remaining balance is forfeited. The grant reads as voided status afterwards. Payment state is not adjusted when payment_adjustment is none, so invoice-backed or externally collected payments may still collect the original amount. Only active grants can be voided; voiding a pending, expired, or fully consumed grant returns a conflict. Retrying a successful void is an idempotent success.
om.Customers.Credits.Grants.UpdateExternalSettlement	POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external	Update the payment settlement status of an externally funded credit grant. Use this endpoint to synchronize the payment state of an external payment with the system so that revenue recognition and credit availability work as expected.
om.Customers.Credits.Balance.Get	GET /openmeter/customers/{customerId}/credits/balance	Get a credit balance.
om.Customers.Credits.Adjustments.Create	POST /openmeter/customers/{customerId}/credits/adjustments	A credit adjustment can be used to make manual adjustments to a customer's credit balance. Supported use-cases: - Usage correction
om.Customers.Credits.Transactions.List	GET /openmeter/customers/{customerId}/credits/transactions	List credit transactions for a customer. Returns an immutable, chronological record of credit movements: funded credits and consumed credits. Transactions are returned in reverse chronological order by default.
om.Customers.Charges.List	GET /openmeter/customers/{customerId}/charges	List customer charges. Returns the customer's charges that are represented as either flat fee or usage-based charges.
om.Customers.Charges.Create	POST /openmeter/customers/{customerId}/charges	Create customer charge.

Entitlements

Method	HTTP	Description
om.Entitlements.ListCustomerAccess	GET /openmeter/customers/{customerId}/entitlement-access

Subscriptions

Method	HTTP	Description
om.Subscriptions.Create	POST /openmeter/subscriptions
om.Subscriptions.List	GET /openmeter/subscriptions
om.Subscriptions.Get	GET /openmeter/subscriptions/{subscriptionId}
om.Subscriptions.Cancel	POST /openmeter/subscriptions/{subscriptionId}/cancel	Cancels the subscription. Will result in a scheduling conflict if there are other subscriptions scheduled to start after the cancelation time.
om.Subscriptions.UnscheduleCancelation	POST /openmeter/subscriptions/{subscriptionId}/unschedule-cancelation	Unschedules the subscription cancelation.
om.Subscriptions.Change	POST /openmeter/subscriptions/{subscriptionId}/change	Closes a running subscription and starts a new one according to the specification. Can be used for upgrades, downgrades, and plan changes.
om.Subscriptions.CreateAddon	POST /openmeter/subscriptions/{subscriptionId}/addons	Add add-on to a subscription.
om.Subscriptions.ListAddons	GET /openmeter/subscriptions/{subscriptionId}/addons	List the add-ons of a subscription.
om.Subscriptions.GetAddon	GET /openmeter/subscriptions/{subscriptionId}/addons/{subscriptionAddonId}	Get an add-on association for a subscription.

Apps

Method	HTTP	Description
om.Apps.List	GET /openmeter/apps	List installed apps.
om.Apps.Get	GET /openmeter/apps/{appId}	Get an installed app.
om.Apps.ListCatalog	GET /openmeter/app-catalog	List available apps.
om.Apps.GetCatalogItem	GET /openmeter/app-catalog/{appType}	Get an app catalog item by type.
om.Apps.Install	POST /openmeter/app-catalog/install	Install an app from the catalog.

Billing

Method	HTTP	Description
om.Billing.ListProfiles	GET /openmeter/profiles	List billing profiles.
om.Billing.CreateProfile	POST /openmeter/profiles	Create a new billing profile. Billing profiles contain the settings for billing and controls invoice generation. An organization can have multiple billing profiles defined. A billing profile is linked to a specific app. This association is established during the billing profile's creation and remains immutable.
om.Billing.GetProfile	GET /openmeter/profiles/{id}	Get a billing profile.
om.Billing.UpdateProfile	PUT /openmeter/profiles/{id}	Update a billing profile.
om.Billing.DeleteProfile	DELETE /openmeter/profiles/{id}	Delete a billing profile. Only such billing profiles can be deleted that are: - not the default profile - not pinned to any customer using customer overrides - only have finalized invoices

Invoices

Method	HTTP	Description
om.Invoices.List	GET /openmeter/billing/invoices	List billing invoices. Returns a page of invoices. Gathering invoices are never included. Use filter to narrow by status, customer, dates, or service period start. Use sort to control ordering.
om.Invoices.Get	GET /openmeter/billing/invoices/{invoiceId}	Get a billing invoice by ID. Returns the full invoice resource including line items, status details, totals, and workflow configuration snapshot.
om.Invoices.Update	PUT /openmeter/billing/invoices/{invoiceId}	Update a billing invoice. Only the mutable fields of the invoice can be edited: description, labels, supplier, customer, workflow settings, and top-level lines. Top-level lines are matched by id; lines without an id are created, and existing lines omitted from lines are deleted. Detailed (child) lines are always computed and cannot be edited directly. Only invoices in draft status can be updated.
om.Invoices.Delete	DELETE /openmeter/billing/invoices/{invoiceId}	Delete a billing invoice. Only standard invoices in draft status can be deleted. Deleting an invoice will also delete all associated line items and workflow configuration.
om.Invoices.Advance	POST /openmeter/billing/invoices/{invoiceId}/advance	Advance a billing invoice. Advances the invoice to the next workflow state. The next state is determined by the invoice's current status and workflow configuration. Only invoices in draft or issued status can be advanced.
om.Invoices.Approve	POST /openmeter/billing/invoices/{invoiceId}/approve	Approve a billing invoice. This call instantly sends the invoice to the customer using the configured billing profile app. This call is valid in two invoice statuses: - draft: the invoice will be sent to the customer, the invoice state becomes issued - manual_approval_needed: the invoice will be sent to the customer, the invoice state becomes issued
om.Invoices.Retry	POST /openmeter/billing/invoices/{invoiceId}/retry	Retry sending a billing invoice. Retry advancing the invoice after a failed attempt. The action can be called when the invoice's statusDetails' actions field contain the "retry" action.
om.Invoices.SnapshotQuantities	POST /openmeter/billing/invoices/{invoiceId}/snapshot-quantities	Snapshot quantities for usage-based line items. This call will snapshot the quantities for all usage based line items in the invoice. This call is only valid in draft.waiting_for_collection status, where the collection period can be skipped using this action.

Tax

Method	HTTP	Description
om.Tax.CreateCode	POST /openmeter/tax-codes
om.Tax.GetCode	GET /openmeter/tax-codes/{taxCodeId}
om.Tax.ListCodes	GET /openmeter/tax-codes
om.Tax.UpsertCode	PUT /openmeter/tax-codes/{taxCodeId}
om.Tax.DeleteCode	DELETE /openmeter/tax-codes/{taxCodeId}

Currencies

Method	HTTP	Description
om.Currencies.List	GET /openmeter/currencies	List currencies supported by the billing system.
om.Currencies.CreateCustomCurrency	POST /openmeter/currencies/custom	Create a custom currency. This operation allows defining your own custom currency for billing purposes.
om.Currencies.ListCostBases	GET /openmeter/currencies/custom/{currencyId}/cost-bases	List cost bases for a currency. For custom currencies, there can be multiple cost bases with different effective_from dates.
om.Currencies.CreateCostBasis	POST /openmeter/currencies/custom/{currencyId}/cost-bases	Create a cost basis for a currency.

Features

Method	HTTP	Description
om.Features.List	GET /openmeter/features	List all features.
om.Features.Create	POST /openmeter/features	Create a feature.
om.Features.Get	GET /openmeter/features/{featureId}	Get a feature by id.
om.Features.Update	PATCH /openmeter/features/{featureId}	Update a feature by id. Currently only the unit_cost field can be updated.
om.Features.Delete	DELETE /openmeter/features/{featureId}	Delete a feature by id.
om.Features.QueryCost	POST /openmeter/features/{featureId}/cost/query	Query the cost of a feature.

LLMCost

Method	HTTP	Description
om.LLMCost.ListPrices	GET /openmeter/llm-cost/prices	List global LLM cost prices. Returns prices with overrides applied if any.
om.LLMCost.GetPrice	GET /openmeter/llm-cost/prices/{priceId}	Get a specific LLM cost price by ID. Returns the price with overrides applied if any.
om.LLMCost.ListOverrides	GET /openmeter/llm-cost/overrides	List per-namespace price overrides.
om.LLMCost.CreateOverride	POST /openmeter/llm-cost/overrides	Create a per-namespace price override.
om.LLMCost.DeleteOverride	DELETE /openmeter/llm-cost/overrides/{priceId}	Delete a per-namespace price override.

Plans

Method	HTTP	Description
om.Plans.List	GET /openmeter/plans	List all plans.
om.Plans.Create	POST /openmeter/plans	Create a new plan.
om.Plans.Update	PUT /openmeter/plans/{planId}	Update a plan by id.
om.Plans.Get	GET /openmeter/plans/{planId}	Get a plan by id.
om.Plans.Delete	DELETE /openmeter/plans/{planId}	Delete a plan by id.
om.Plans.Archive	POST /openmeter/plans/{planId}/archive	Archive a plan version.
om.Plans.Publish	POST /openmeter/plans/{planId}/publish	Publish a plan version.

Addons

Method	HTTP	Description
om.Addons.List	GET /openmeter/addons	List all add-ons.
om.Addons.Create	POST /openmeter/addons	Create a new add-on.
om.Addons.Update	PUT /openmeter/addons/{addonId}	Update an add-on by id.
om.Addons.Get	GET /openmeter/addons/{addonId}	Get add-on by id.
om.Addons.Delete	DELETE /openmeter/addons/{addonId}	Soft delete add-on by id.
om.Addons.Archive	POST /openmeter/addons/{addonId}/archive	Archive an add-on version.
om.Addons.Publish	POST /openmeter/addons/{addonId}/publish	Publish an add-on version.

PlanAddons

Method	HTTP	Description
om.PlanAddons.List	GET /openmeter/plans/{planId}/addons	List add-ons associated with a plan.
om.PlanAddons.Create	POST /openmeter/plans/{planId}/addons	Add an add-on to a plan.
om.PlanAddons.Get	GET /openmeter/plans/{planId}/addons/{planAddonId}	Get an add-on association for a plan.
om.PlanAddons.Update	PUT /openmeter/plans/{planId}/addons/{planAddonId}	Update an add-on association for a plan.
om.PlanAddons.Delete	DELETE /openmeter/plans/{planId}/addons/{planAddonId}	Remove an add-on from a plan.

Defaults

Method	HTTP	Description
om.Defaults.GetOrganizationTaxCodes	GET /openmeter/defaults/tax-codes
om.Defaults.UpdateOrganizationTaxCodes	PUT /openmeter/defaults/tax-codes

Governance

Method	HTTP	Description
om.Governance.QueryAccess	POST /openmeter/governance/query	Query feature access for a list of customers. The endpoint resolves each provided identifier to a customer and returns the access status for the requested features, plus optional credit balance availability. Designed to be called on a fixed refresh interval and the query response is intended to be cached.

Error Handling

A non-2xx response returns an *APIError carrying the problem-details fields (StatusCode, Status, Type, Title, Detail, Instance) from the response where available. Client-side validation errors such as an empty path ID are returned before any HTTP request is made.

package main

import (
    "context"
    "errors"
    "log"

    "github.com/openmeterio/openmeter/api/v3/client"
)

func main() {
    om, err := openmeter.New("https://openmeter.cloud/api/v3", openmeter.WithToken("om_..."))
    if err != nil {
        log.Fatal(err)
    }

    _, err = om.Meters.Get(context.Background(), "unknown")
    if err != nil {
        var apiErr *openmeter.APIError
        if errors.As(err, &apiErr) {
            log.Printf("%d %s %s", apiErr.StatusCode, apiErr.Title, apiErr.Type)
            return
        }
        log.Fatal(err)
    }
}

Pagination and Streaming

Paginated list operations also emit ListAll helpers that return iter.Seq2[T, error]. Text responses such as meter CSV export emit a byte returning method and a Stream variant for callers that want an io.ReadCloser.

Cursor-paginated responses report their position as Next and Previous on CursorMetaPage. Both are opaque cursor tokens: pass them back verbatim as the page[after] / page[before] query parameters (CursorPageParams.After / CursorPageParams.Before); do not parse or construct them.

Iterating with Before set walks pages backward while the items within each page stay in forward order, so the resulting stream is not globally sorted.

for meter, err := range om.Meters.ListAll(ctx, openmeter.MeterListParams{}) {
    if err != nil {
        log.Fatal(err)
    }
    log.Println(meter.Key)
}

stream, err := om.Meters.QueryCSVStream(ctx, "meter-id", openmeter.MeterQueryRequest{})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()