Node.js billing integration

Use this guide to integrate Narev Cloud billing on any Node.js server without coupling your app to a single billing provider. The pattern works wherever you run the Vercel AI SDK on the server (Next.js route handlers, Hono, Express, Fastify, or a plain Node script behind your API). You’ll:

Wrap all model calls with @ai-billing middleware.
Attach consistent billing tags for attribution.
Keep your provider logic modular so you can use Polar, Stripe, or another destination.

Before you start

You already call generateText, streamText, or generateObject from the Vercel AI SDK on the server.
You already send AI calls through a shared model helper.
You have a billing destination selected.

If you want provider-specific setup (destination config, metering strategy, and customer sync), use:

Building with Next.js and want billing UI components (CreditUsagePolar, credit top-up flows)? Add @ai-billing/nextjs. The middleware pattern on this page still applies.

Install dependencies

Install middleware for your AI provider. This example uses the Vercel AI Gateway:

pnpm add @ai-billing/gateway ai

You can swap @ai-billing/gateway for a provider package such as @ai-billing/openai, @ai-billing/anthropic, or @ai-billing/openrouter. See the @ai-billing SDK overview. Install your billing-platform package separately. For example:

Polar: @ai-billing/polar
Stripe: @ai-billing/stripe
Lago: @ai-billing/lago
OpenMeter: @ai-billing/openmeter

Configure environment variables

Set provider and destination credentials in your server environment (.env, deployment secrets, or your host’s env config):

# Required when using @ai-billing/gateway outside Vercel deployments
AI_GATEWAY_API_KEY=****

Add destination-specific variables in the billing platform guide for your provider.

Build a platform-agnostic billing wrapper

Create lib/ai/billing.ts and inject destinations from a separate module:

lib/ai/billing.ts

import { wrapLanguageModel } from 'ai';
import type { LanguageModelV3 } from '@ai-sdk/provider';
import { createGatewayV3Middleware } from '@ai-billing/gateway';
import { getBillingDestinations } from './destinations';

let _billingMiddleware: ReturnType<typeof createGatewayV3Middleware> | null =
  null;
let _initAttempted = false;

function getBillingMiddleware() {
  if (_initAttempted) return _billingMiddleware;
  _initAttempted = true;

  const destinations = getBillingDestinations();
  if (destinations.length === 0) return null;

  _billingMiddleware = createGatewayV3Middleware({ destinations });
  return _billingMiddleware;
}

export function getBillingWrappedModel(model: LanguageModelV3): LanguageModelV3 {
  const middleware = getBillingMiddleware();
  if (!middleware) return model; // Keep local/dev environments resilient.
  return wrapLanguageModel({ model, middleware });
}

This keeps your server integration stable while destination details live in platform-specific docs.

Route all model access through one provider helper

Create a single model entrypoint in lib/ai/providers.ts:

lib/ai/providers.ts

import { gateway } from 'ai';
import { getBillingWrappedModel } from './billing';

export function getLanguageModel(modelId: string) {
  return getBillingWrappedModel(gateway.languageModel(modelId));
}

Use getLanguageModel(...) everywhere. If a handler bypasses this helper, that usage is not billed.

Attach billing tags on every generation call

In any server handler that calls the model, include providerOptions['ai-billing-tags']:

import { streamText } from 'ai';
import { getLanguageModel } from './ai/providers';

const result = streamText({
  model: getLanguageModel(chatModel),
  messages: modelMessages,
  providerOptions: {
    'ai-billing-tags': {
      userId: session.user.id,
      modelId: chatModel,
      chatId: id,
      userType,
    },
  },
});

The handler can be a Next.js route, a Hono app.post, an Express router, or any other HTTP entrypoint. The billing contract is the same. Minimum tag:

userId

Recommended tags:

modelId
chatId or requestId
userType, workspaceId, or feature

Organize your integration

Use this structure:

lib/ai/billing.ts: middleware wrapper and wrapLanguageModel helper.
lib/ai/destinations.ts: billing-platform destinations.
lib/ai/providers.ts: shared model resolver.
Your HTTP handlers: generation routes with billing tags.

Verify billing coverage

Trigger a generation request and confirm your billing platform receives usage events.
Trigger non-chat AI features and confirm your billing platform receives those usage events.
Confirm every AI path uses getLanguageModel(...).
Confirm userId is always present in ai-billing-tags.

Troubleshooting

No usage events appear

Confirm your destination config loads during server startup.
Confirm each handler uses getLanguageModel(...).
Confirm required provider credentials are available at runtime.

Some routes bill and others don’t

Audit streamText, generateText, and generateObject usage across your codebase.
Move direct provider calls behind your shared helper.

What to do next

Choose your billing destination guide:

Bootup

Real-time Pricing

API Reference

Node.js

Node.js billing integration

Before you start

Install dependencies

Configure environment variables

Build a platform-agnostic billing wrapper

Route all model access through one provider helper

Attach billing tags on every generation call

Organize your integration

Verify billing coverage

Troubleshooting

No usage events appear

Some routes bill and others don’t

What to do next

​Node.js billing integration

​Before you start

​Install dependencies

​Configure environment variables

​Build a platform-agnostic billing wrapper

​Route all model access through one provider helper

​Attach billing tags on every generation call

​Organize your integration

​Verify billing coverage

​Troubleshooting

​No usage events appear

​Some routes bill and others don’t

​What to do next

Node.js billing integration

Before you start

Install dependencies

Configure environment variables

Build a platform-agnostic billing wrapper

Route all model access through one provider helper

Attach billing tags on every generation call

Organize your integration

Verify billing coverage

Troubleshooting

No usage events appear

Some routes bill and others don’t

What to do next