Cost Events

Cost Insights works by allowing you to add a special _cost property to any event you ingest through OurPay’s Event Ingestion API. These costs are then aggregated and made available through the Metrics API alongside revenue metrics.

The `_cost` Property

Basic Structure

To track costs, add a _cost property to your event’s metadata when ingesting events.

TypeScript (SDK)

import { createOurPay } from "@ourpay-dev/sdk/2026-10";

const ourpay = createOurPay({
  accessToken: process.env.OURPAY_ACCESS_TOKEN ?? "",
});

await ourpay.events.ingest({
  events: [
    {
      name: "llm.inference",
      external_customer_id: "user_123",
      metadata: {
        _cost: {
          amount: 0.025,
          currency: "usd",
        },
      },
    },
  ],
});

cURL

POST https://api.ourpay.dev/v1/events/ingest
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "events": [
    {
      "name": "llm.inference",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 0.025,
          "currency": "usd"
        }
      }
    }
  ]
}

Cost Metadata Schema

The _cost property has the following structure:

amount (required): The cost amount in cents as a decimal number
- Example: 0.025 for $0.00025 (a fraction of a cent)
- Example: 150 for $1.50
- Supports up to 17 digits with 12 decimal places for precision
currency (required): The currency code
- Currently only "usd" is supported

Amount must be in cents: The amount field represents the cost in cents, not dollars. For example, 100 = \$1.00, 0.5 = \$0.005 (half a cent), and 0.001 = \$0.00001 (one hundredth of a cent).

Use Cases

AI/LLM Applications

Track the cost of LLM API calls per customer:

TypeScript

import { createOurPay } from "@ourpay-dev/sdk/2026-10";
import OpenAI from "openai";

const ourpay = createOurPay({
  accessToken: process.env.OURPAY_ACCESS_TOKEN ?? "",
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: "Explain usage-based billing in one sentence.",
});

if (!response.usage) {
  throw new Error("OpenAI did not return token usage");
}

const { input_tokens, output_tokens, input_tokens_details } = response.usage;
const cachedTokens = input_tokens_details.cached_tokens ?? 0;
const uncachedTokens = input_tokens - cachedTokens;
const longContext = input_tokens > 272_000;
const inputMultiplier = longContext ? 2 : 1;
const outputMultiplier = longContext ? 1.5 : 1;

// Standard text-token rates in USD per million, checked September 13, 2026.
const inputCost = (uncachedTokens / 1_000_000) * 10 * inputMultiplier;
const cachedCost = (cachedTokens / 1_000_000) * 1 * inputMultiplier;
const outputCost = (output_tokens / 1_000_000) * 50 * outputMultiplier;
const totalCost = (inputCost + cachedCost + outputCost) * 100;

// Track the cost in OurPay
await ourpay.events.ingest({
  events: [
    {
      name: "llm.inference",
      external_customer_id: "user_123",
      metadata: {
        _cost: {
          amount: totalCost,
          currency: "usd",
        },
        _llm: {
          vendor: "openai",
          model: response.model,
          input_tokens: input_tokens,
          output_tokens: output_tokens,
          total_tokens: response.usage.total_tokens,
        },
      },
    },
  ],
});

This is a text-token cost estimate using OpenAI’s GPT-6 Astra rates, checked September 13, 2026. The standard rates are

10 per million uncached input tokens,

1 per million cached input tokens and $50 per million output tokens. The example applies the documented long-context multipliers above 272,000 input tokens. Cache-write charges, tools, other service tiers and account-specific charges need separate entries. Keep rates configurable and reconcile estimates against provider billing.

Infrastructure Costs

Track compute, storage, or API costs:

{
  "events": [
    {
      "name": "video.processing",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 45.5, // $0.455
          "currency": "usd"
        },
        "duration_seconds": 120,
        "resolution": "1080p"
      }
    }
  ]
}

Third-Party Service Costs

Track costs from external services:

{
  "events": [
    {
      "name": "email.sent",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 0.0001, // $0.000001
          "currency": "usd"
        },
        "provider": "sendgrid",
        "recipients": 1
      }
    }
  ]
}

Best Practices

Track Costs in Real-Time

Ingest cost events as they occur to maintain accurate, up-to-date metrics: Record the event after the provider returns usage, as in the example above. Use a stable event name such as llm.inference and keep the model identifier in metadata. Queue ingestion retries with a stable event identifier so a transient network failure does not count the same request twice.

Use Precise Amounts

The amount field supports up to 12 decimal places, perfect for tracking micro-costs:

{
  "_cost": {
    "amount": 0.000125, // $0.00000125
    "currency": "usd"
  }
}

Add Context with Additional Metadata

Combine _cost with other metadata to understand cost drivers:

{
  "metadata": {
    "_cost": {
      "amount": 0.05, // $0.0005
      "currency": "usd"
    },
    "model": "gpt-6-astra",
    "tokens": 1000,
    "feature": "chatbot"
  }
}

Bootup

Features

Integrate

Merchant of Record (MoR)

The `_cost` Property

Basic Structure

Cost Metadata Schema

Use Cases

AI/LLM Applications

Infrastructure Costs

Third-Party Service Costs

Best Practices

Track Costs in Real-Time

Use Precise Amounts

Add Context with Additional Metadata

​The _cost Property

​Basic Structure

​Cost Metadata Schema

​Use Cases

​AI/LLM Applications

​Infrastructure Costs

​Third-Party Service Costs

​Best Practices

​Track Costs in Real-Time

​Use Precise Amounts

​Add Context with Additional Metadata

The `_cost` Property

Basic Structure

Cost Metadata Schema

Use Cases

AI/LLM Applications

Infrastructure Costs

Third-Party Service Costs

Best Practices

Track Costs in Real-Time

Use Precise Amounts

Add Context with Additional Metadata