Cost Tracking

Track the cost of serving each customer and monitor gross margin

Cost tracking lets you record the variable cost of serving each customer — AI inference, third-party API calls, cloud compute, data enrichment, or any other spend that varies with usage. Paygentic aggregates these cost events per customer and period, so you can compare total cost against revenue and understand your gross margin at the customer level.

Unlike billable metrics (which measure what your customers consume for billing), cost metrics measure what you pay to serve them.

Common use cases:

• AI-powered products — Track LLM token costs, embedding calls, and agent compute per customer
• Data enrichment platforms — Record the cost of third-party API calls (geocoding, credit checks, identity verification) attributed to each customer
• Document processing — Attribute OCR, translation, or extraction pipeline costs to the customers who triggered them
• Multi-tenant SaaS — Track cloud compute or storage spend that varies by customer workload

How it works

1. Create a cost metric that defines what you measure and how to aggregate it
2. After each operation that incurs a cost, send a cost event to POST /v0/events with the dollar amount
3. Paygentic aggregates cost events by customer and time period
4. Query the aggregated costs via GET /v0/costs/{id}/summary to build margin dashboards or feed your own analytics

Before you begin

• An API key for your organization
• A product created in Paygentic (you need the productId)
• Your customer IDs available at the time operations are performed

Step 1: Create a cost metric

A cost metric defines which events contribute to cost tracking, how to extract the amount, and how to slice costs by dimension. Every cost must be attached to a product via productId.

cURL

curl -X POST "https://api.paygentic.io/v0/costs" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "metered",
    "name": "AI Inference Cost",
    "eventType": "cost.ai.inference",
    "valueProperty": "$.amount",
    "aggregation": "SUM",
    "unitCost": 1,
    "currency": "USD",
    "productId": "prod_YOUR_PRODUCT_ID",
    "groupBy": {
      "provider": "$.provider",
      "operation": "$.operation"
    }
  }'

const response = await fetch('https://api.paygentic.io/v0/costs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'metered',
    name: 'AI Inference Cost',
    eventType: 'cost.ai.inference',
    valueProperty: '$.amount',
    aggregation: 'SUM',
    unitCost: 1,
    currency: 'USD',
    productId: 'prod_YOUR_PRODUCT_ID',
    groupBy: {
      provider: '$.provider',
      operation: '$.operation',
    },
  }),
});

const cost = await response.json();
// { id: "cst_abc123", object: "cost", name: "AI Inference Cost", ... }

Response:

{
  "id": "cst_abc123",
  "object": "cost",
  "type": "metered",
  "name": "AI Inference Cost",
  "currency": "USD",
  "unitCost": "1",
  "unit": null,
  "aggregation": "SUM",
  "eventType": "cost.ai.inference",
  "valueProperty": "$.amount",
  "groupBy": {
    "provider": "$.provider",
    "operation": "$.operation"
  },
  "productId": "prod_YOUR_PRODUCT_ID",
  "merchantId": "org_YOUR_ORG_ID",
  "createdAt": "2026-02-01T10:00:00Z",
  "updatedAt": "2026-02-01T10:00:00Z",
  "deletedAt": null
}

Step 2: Send cost events

After each operation that incurs a cost, send an event with the dollar amount. Use the same POST /v0/events endpoint as meter events — the type field links the event to your cost metric.

cURL

curl -X POST "https://api.paygentic.io/v0/events" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cost.ai.inference",
    "source": "https://api.myapp.com",
    "subject": "cus_abc123",
    "data": {
      "amount": 0.0042,
      "provider": "anthropic",
      "operation": "document-extraction"
    },
    "idempotencyKey": "job_xyz789-cost"
  }'

await fetch('https://api.paygentic.io/v0/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'cost.ai.inference',
    source: 'https://api.myapp.com',
    subject: customerId,
    data: {
      amount: result.cost,
      provider: result.provider,
      operation: 'document-extraction',
    },
    idempotencyKey: `${jobId}-cost`,
  }),
});

import requests

requests.post(
    "https://api.paygentic.io/v0/events",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "type": "cost.ai.inference",
        "source": "https://api.myapp.com",
        "subject": customer_id,
        "data": {
            "amount": result["cost"],
            "provider": result["provider"],
            "operation": "document-extraction",
        },
        "idempotencyKey": f"{job_id}-cost",
    },
)

Send cost events after the operation completes, once you have the actual cost from your provider. The amount field should be the total cost in the currency configured on the cost metric.

Calculating the amount

The amount you record should reflect what you actually paid — not an estimate. Retrieve this from your provider’s response or invoice data:

// Example: LLM provider returns token counts, multiply by per-token rate
function computeInferenceCost(inputTokens, outputTokens, model) {
  const rates = {
    'claude-3-5-sonnet': { input: 0.000003, output: 0.000015 },
    'claude-3-haiku':    { input: 0.00000025, output: 0.00000125 },
  };
  const r = rates[model];
  return (inputTokens * r.input) + (outputTokens * r.output);
}

// Example: third-party API with a flat per-call rate
function computeApiCallCost(callCount, pricePerCall) {
  return callCount * pricePerCall;
}

Step 3: Query cost summary

Use GET /v0/costs/{id}/summary to retrieve aggregated cost data for a specific cost metric over a time window.

cURL

curl "https://api.paygentic.io/v0/costs/cst_abc123/summary?from=2026-02-01T00:00:00Z&to=2026-03-01T00:00:00Z&subject=cus_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

const params = new URLSearchParams({
  from: '2026-02-01T00:00:00Z',
  to: '2026-03-01T00:00:00Z',
  subject: 'cus_abc123',
});

const response = await fetch(
  `https://api.paygentic.io/v0/costs/cst_abc123/summary?${params}`,
  { headers: { 'Authorization': 'Bearer sk_live_YOUR_API_KEY' } }
);

const summary = await response.json();

Response:

{
  "object": "cost",
  "id": "cst_abc123",
  "name": "AI Inference Cost",
  "type": "metered",
  "currency": "USD",
  "eventType": "cost.ai.inference",
  "totalCost": 42.50,
  "totalQuantity": 42500
}

Group by dimensions

Add groupBy to break down costs by the dimensions you configured on the cost metric:

curl "https://api.paygentic.io/v0/costs/cst_abc123/summary?from=2026-02-01T00:00:00Z&to=2026-03-01T00:00:00Z&groupBy=provider,operation" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response includes a groups array:

{
  "object": "cost",
  "id": "cst_abc123",
  "name": "AI Inference Cost",
  "type": "metered",
  "currency": "USD",
  "eventType": "cost.ai.inference",
  "totalCost": 42.50,
  "totalQuantity": 42500,
  "groups": [
    { "dimensions": { "provider": "anthropic", "operation": "extraction" }, "quantity": 30000, "cost": 30.00 },
    { "dimensions": { "provider": "anthropic", "operation": "summarization" }, "quantity": 12500, "cost": 12.50 }
  ]
}

Time-series breakdown

Add window to get a time-series breakdown:

curl "https://api.paygentic.io/v0/costs/cst_abc123/summary?from=2026-02-01T00:00:00Z&to=2026-02-03T00:00:00Z&window=DAY" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response includes a timeSeries array:

{
  "object": "cost",
  "id": "cst_abc123",
  "name": "AI Inference Cost",
  "type": "metered",
  "currency": "USD",
  "eventType": "cost.ai.inference",
  "totalCost": 15.00,
  "totalQuantity": 15000,
  "timeSeries": [
    { "windowStart": "2026-02-01T00:00:00Z", "windowEnd": "2026-02-02T00:00:00Z", "quantity": 8000, "cost": 8.00 },
    { "windowStart": "2026-02-02T00:00:00Z", "windowEnd": "2026-02-03T00:00:00Z", "quantity": 7000, "cost": 7.00 }
  ]
}

Filter by dimension values

Use filterGroupBy to narrow results to specific dimension values:

curl "https://api.paygentic.io/v0/costs/cst_abc123/summary?from=2026-02-01T00:00:00Z&to=2026-03-01T00:00:00Z&filterGroupBy=%7B%22provider%22%3A%22anthropic%22%7D" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

The filterGroupBy value is a JSON-encoded object. Keys must match those defined in the cost’s groupBy configuration.

Managing costs

List costs

Retrieve all costs for your organization, optionally filtered by product:

curl "https://api.paygentic.io/v0/costs?productId=prod_YOUR_PRODUCT_ID&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response:

{
  "object": "list",
  "data": [
    { "id": "cst_abc123", "object": "cost", "type": "metered", "name": "AI Inference Cost", "..." : "..." }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

Get a single cost

curl "https://api.paygentic.io/v0/costs/cst_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Update a cost

All fields are optional — only include the fields you want to change:

curl -X PATCH "https://api.paygentic.io/v0/costs/cst_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LLM Inference Cost",
    "unitCost": 1.5
  }'

Delete a cost

Deleting a cost performs a soft delete. The cost is no longer returned in list queries, but historical data is preserved.

curl -X DELETE "https://api.paygentic.io/v0/costs/cst_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 204 No Content on success.

Tracking multiple cost dimensions

Create separate cost metrics for each distinct type of spend. Each metric has its own eventType and tracks independently.

Example: separate metrics for different cost categories

# LLM inference
curl -X POST "https://api.paygentic.io/v0/costs" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "metered", "name": "LLM Inference", "eventType": "cost.ai.inference", "valueProperty": "$.amount", "aggregation": "SUM", "unitCost": 1, "currency": "USD", "productId": "prod_YOUR_PRODUCT_ID" }'

# Third-party data enrichment
curl -X POST "https://api.paygentic.io/v0/costs" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "metered", "name": "Data Enrichment", "eventType": "cost.enrichment", "valueProperty": "$.amount", "aggregation": "SUM", "unitCost": 1, "currency": "USD", "productId": "prod_YOUR_PRODUCT_ID" }'

# Cloud compute
curl -X POST "https://api.paygentic.io/v0/costs" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "metered", "name": "Compute", "eventType": "cost.compute", "valueProperty": "$.amount", "aggregation": "SUM", "unitCost": 1, "currency": "USD", "productId": "prod_YOUR_PRODUCT_ID" }'

Events are sent with the matching type:

{ "type": "cost.ai.inference", "subject": "cus_abc123", "data": { "amount": 0.0042, "operation": "extraction" } }
{ "type": "cost.enrichment",   "subject": "cus_abc123", "data": { "amount": 0.0010, "provider": "clearbit" } }
{ "type": "cost.compute",      "subject": "cus_abc123", "data": { "amount": 0.0023, "region": "us-east-1" } }

Multiple cost metrics can read from the same eventType. This lets you extract and aggregate different fields from the same event — for example, tracking GPU cost and CPU cost separately from a single compute event.

A single event can also be processed by both a billable metric and a cost metric simultaneously. For example, an ai.inference event can drive customer billing via a billable metric while the same event feeds your cost tracking — no need to send separate events.

API reference

Create cost request

Field	Type	Required	Description
type	string	Yes	Must be "metered".
name	string	Yes	Display name for this cost metric.
eventType	string	Yes	CloudEvents type that identifies the metered event. Convention: use a cost. prefix (e.g. cost.ai.inference).
aggregation	enum	Yes	How to combine values: SUM, COUNT, AVG, MIN, MAX, UNIQUE_COUNT, or LATEST.
unitCost	number	Yes	Cost per unit of measured quantity. Must be non-negative (0–1,000,000).
currency	string	Yes	ISO 4217 currency code (e.g. "USD"). Must be enabled on your organization.
productId	string	Yes	The product this cost belongs to.
valueProperty	string	Conditional	JSONPath to extract the numeric value from event data (e.g. $.amount). Required when aggregation is SUM, AVG, MIN, MAX, or LATEST.
unit	string	No	Label for the metered unit (e.g. "token", "request").
groupBy	object	No	Map of dimension names to JSONPath expressions. Allows slicing total cost by provider, operation, region, etc.

Cost response object

Field	Type	Description
id	string	Unique identifier with cst_ prefix.
object	string	Always "cost".
type	string	Always "metered".
name	string	Display name.
currency	string	ISO 4217 currency code.
unitCost	string	Decimal as string to avoid floating-point precision loss.
unit	string | null	Unit label, if set.
aggregation	enum | null	SUM, COUNT, AVG, MIN, MAX, UNIQUE_COUNT, or LATEST.
eventType	string | null	CloudEvents type for metered costs.
valueProperty	string | null	JSONPath for value extraction.
groupBy	object | null	Dimension-to-JSONPath map.
productId	string	Product this cost belongs to.
merchantId	string	Organization that owns this cost.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 last-update timestamp.
deletedAt	string | null	Soft-delete timestamp. Always null for active costs.

Cost summary query parameters

Parameter	Type	Required	Description
from	string	Yes	Start of query window (ISO 8601).
to	string	Yes	End of query window (ISO 8601).
subject	string	No	Filter to a specific customer. When omitted, aggregates across all subjects.
groupBy	string	No	Comma-separated dimension keys to group results by.
window	enum	No	Time-series granularity: MINUTE, HOUR, or DAY.
filterGroupBy	string	No	JSON-encoded dimension filter (e.g. {"provider":"anthropic"}). Keys must match the cost’s groupBy configuration.

Cost summary response

Field	Type	Description
object	string	Always "cost".
id	string	Cost ID.
name	string	Cost name.
type	string	Always "metered".
currency	string	ISO 4217 currency code.
eventType	string	CloudEvents type.
totalCost	number | null	Total cost for the query window. null if usage data could not be computed.
totalQuantity	number | null	Total usage quantity. null if usage was not computed.
groups	array	Per-group breakdown. Present when groupBy is specified. Each entry has dimensions, quantity, and cost.
timeSeries	array	Time-series breakdown. Present when window is specified. Each entry has windowStart, windowEnd, quantity, and cost.

Cost event data fields

The data payload is arbitrary JSON. Only amount (or whichever path valueProperty points to) is required — all other fields are optional context that improves filtering and dimension slicing.

Field	Description
amount	Cost in the metric’s currency. Required — this is the value extracted by valueProperty.
provider	The vendor or service that incurred the cost (e.g. "anthropic", "aws", "clearbit").
operation	The type of operation performed (e.g. "document-extraction", "geocoding", "ocr").
region	The compute or data region, if relevant for cost attribution.

Any other fields you include in data can be referenced in groupBy on your cost metric.

Idempotency

Use idempotencyKey to avoid double-counting costs when retrying failed requests:

// Generate a deterministic key from the operation that incurred the cost
const idempotencyKey = `${jobId}-${eventType}`;

• If two events share the same idempotencyKey, only the first is recorded
• The deduplication window is 24 hours
• Omitting idempotencyKey means retries will create duplicate cost entries

Best practices

Send cost events after the operation completes. You need the actual cost from your provider — don’t estimate upfront and correct later.

Use idempotencyKey on every event. Derive it from a stable operation identifier (job ID, request ID) to make retries safe.

One cost event per billable operation, not per customer request. A single customer request may trigger multiple downstream calls — track each one individually for accurate attribution.

Separate metrics for different cost categories. Inference, enrichment, and compute have different unit economics. Tracking them independently makes it easier to understand where margin pressure is coming from.

Next steps

• Meter Events — The underlying event infrastructure that cost tracking builds on
• Billable Metrics — Define what you measure for customer billing
• Metered Entitlements — Gate customer access based on usage quotas