​

OpenMeter billing platform integration

• Create the @ai-billing/openmeter destination.
• Map usage events to OpenMeter customers via CloudEvents subject.
• Sync customer records when users sign up and assign subject keys.

​

Metering strategy

​

Before you start

​

Install OpenMeter dependencies

pnpm add @ai-billing/openmeter

​

Configure environment variables

OPENMETER_API_KEY=****
# Set to your OpenMeter API base URL (OpenMeter Cloud, self-hosted, or Kong)
OPENMETER_API_URL=https://openmeter.cloud

​

Create OpenMeter billing destinations

import { createOpenMeterDestination } from '@ai-billing/openmeter';

export function getBillingDestinations() {
  const openMeterApiKey = process.env.OPENMETER_API_KEY;

  if (!openMeterApiKey) return [];

  return [
    createOpenMeterDestination({
      apiKey: openMeterApiKey,
      apiUrl: process.env.OPENMETER_API_URL,
      eventType: 'llm_usage',
      customerIdKey: 'userId',
    }),
  ];
}

​

Sync OpenMeter customers when users sign up

export async function createOpenMeterCustomer(
  name: string,
  userId: string,
) {
  const apiKey = process.env.OPENMETER_API_KEY;
  const apiUrl = process.env.OPENMETER_API_URL ?? 'https://openmeter.cloud';

  if (!apiKey) return;

  try {
    const response = await fetch(`${apiUrl}/api/v1/customers`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name,
        key: userId,
        usageAttribution: { subjectKeys: [userId] },
      }),
    });

    if (!response.ok) {
      throw new Error(`OpenMeter API returned ${response.status}`);
    }
  } catch (error) {
    console.error('[ai-billing] Failed to create OpenMeter customer:', error);
  }
}

if (newUser) {
  await createOpenMeterCustomer(validatedData.email, newUser.id);
}

​

Required tag contract

providerOptions: {
  'ai-billing-tags': {
    userId: session.user.id,
    modelId: chatModel,
    chatId: id,
  },
}

• userId in ai-billing-tags must match the CloudEvents subject and the customer subject key.
• Each user should have one OpenMeter customer record.
• If userId is missing, the destination skips the event to avoid ingesting anonymous usage.

​

Verify OpenMeter metering

1. Register a new user and confirm an OpenMeter customer exists with key = userId.
2. Trigger a model call and confirm a CloudEvent with type llm_usage appears in OpenMeter.
3. Validate the data payload contains cost_nanos, currency, and your route context tags.
4. Confirm OPENMETER_API_URL points at the OpenMeter instance you are checking.

​

Common issues

​

Events appear but don’t map to customers

• Confirm userId exists in ai-billing-tags.
• Confirm destination uses customerIdKey: 'userId'.
• Confirm customer creation assigns subjectKeys: [userId] in usageAttribution.

​

No events arrive in OpenMeter

• Confirm OPENMETER_API_KEY is present at runtime.
• Confirm the meter event type matches your OpenMeter configuration.
• Confirm OPENMETER_API_URL matches your deployment (OpenMeter Cloud vs self-hosted).
• Confirm framework routes call the billing-wrapped model helper.
• Confirm each billing event includes a defined cost (attach a price resolver if needed).

​

Events are skipped silently

• OpenMeter skips events when no customer identity tag is found. Confirm userId is set on every generation call.