​
Prerequisites

We recommend using the Sandbox environment for this guide so you can test without processing real payments.

​
Step 1: Install Dependencies

npm install @macropay/ingestion @macropay/sdk ai @ai-sdk/openai

​
Step 2: Create a Meter

A Meter tracks usage events and computes aggregated values for billing. Create one in the Macropay dashboard:
  1. Go to Usage Based Billing > Meters
  2. Click Create Meter
  3. Configure:
    • Name: llm-tokens
    • Filter: Match events named llm-tokens
    • Aggregation: sum on the totalTokens property
The meter will aggregate all token usage per customer per billing period.

​
Step 3: Create a Metered Product

  1. Go to Products and create a new product (or edit an existing subscription product)
  2. Add a Metered Price:
    • Meter: Select llm-tokens
    • Unit price: Set your price per 1,000 tokens (e.g., $0.01 per 1k tokens)
    • Billing interval: Monthly
Customers who subscribe to this product will be billed based on their actual token usage each billing period.

​
Step 4: Wrap Your AI Model

​
TypeScript (Vercel AI SDK)

Use the @macropay/ingestion library to automatically track token usage from any @ai-sdk/* model: 
// src/lib/llm.ts
import { Ingestion } from "@macropay/ingestion";
import { LLMStrategy } from "@macropay/ingestion/strategies/LLM";
import { openai } from "@ai-sdk/openai";

export const llmIngestion = Ingestion({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
})
  .strategy(new LLMStrategy(openai("gpt-4o")))
  .ingest("llm-tokens");

​
Python (PydanticAI)

# llm.py
import os
from macropay.ingestion import Ingestion
from macropay.ingestion.strategies import PydanticAIStrategy

ingestion = Ingestion(os.environ["MACROPAY_ACCESS_TOKEN"])
strategy = ingestion.strategy(PydanticAIStrategy, "llm-tokens")

​
Step 5: Use in Your API Route

​
TypeScript (Next.js)

// src/app/api/chat/route.ts
import { generateText } from "ai";
import { llmIngestion } from "@/lib/llm";

export async function POST(req: Request) {
  const { prompt, customerId }: { prompt: string; customerId: string } =
    await req.json();

  // Get the wrapped model -- pass customerId to attribute usage
  const model = llmIngestion.client({
    customerId,
  });

  const { text } = await generateText({
    model,
    system: "You are a helpful assistant.",
    prompt,
  });

  return Response.json({ text });
}
Every call to generateText (or streamText) automatically sends an ingestion event to Macropay with the token counts.

​
Python (FastAPI + PydanticAI)

# main.py
from fastapi import FastAPI
from pydantic import BaseModel
from pydantic_ai import Agent
from llm import strategy

app = FastAPI()
agent = Agent("gpt-4o")

class ChatRequest(BaseModel):
    prompt: str
    customer_id: str

@app.post("/api/chat")
async def chat(req: ChatRequest):
    result = agent.run_sync(req.prompt)

    # Send token usage to Macropay for billing
    strategy.ingest(req.customer_id, result)

    return {"text": result.output}

​
Step 6: View Usage in Dashboard

Once events are flowing, you can monitor usage in the Macropay dashboard:
  1. Go to Usage Based Billing > Meters
  2. Select your llm-tokens meter
  3. View per-customer usage and aggregated totals
  4. Customers can also view their estimated charges in the Customer Portal

​
Step 7: Automatic Billing

At the end of each billing period, Macropay automatically:
  1. Reads the aggregated meter value for each customer
  2. Calculates the charge based on your metered price
  3. Charges the customer’s payment method on file
  4. Generates an invoice
No additional code is required. Customers are billed for exactly what they use.

​
Adding Cost Tracking (Optional)

Track your upstream AI costs alongside customer billing to monitor margins: 
const llmIngestion = Ingestion({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
})
  .strategy(new LLMStrategy(openai("gpt-4o")))
  .cost((ctx) => ({
    amount: Math.ceil(ctx.inputTokens * 0.0025 + ctx.outputTokens * 0.01),
    currency: "usd",
  }))
  .ingest("llm-tokens");
View cost insights in the dashboard under Cost Insights to see your margins per customer.

​
What’s Next?

Usage Based Billing

Deep dive into meters, events, and billing

Ingestion Strategies

Explore S3, streaming, and custom strategies

Meter Credits

Grant prepaid credits against meters

Cost Insights

Track upstream costs and margins