Skip to main content

Margin

Per-customer margin snapshots.

Limitr can compute per-customer margin snapshots without any external tooling. Because every enforcement call runs through credits with overhead_cost and price defined, Limitr knows exactly what each customer's consumption has cost you and what it's generated in revenue.

For production margin tracking

Use Limitr Cloud, which surfaces live per-customer margin across the full billing period — including subscription revenue, plan changes, and historical data — rather than the current in-process meter state.

How it works​

Margin tracking is a function of how accurately you define two fields on your discrete credits:

overhead_cost — What this credit costs you per unit, in runes. Your actual provider cost: what you pay Anthropic per token, AWS per GB, or your GPU provider per second.

price — What you charge per unit, in runes. The amount that appears on your customer's invoice.

Given these two values and the metered consumption per customer per entitlement, Limitr calculates:

cost    = sum(overhead_cost × metered_value) per entitlement
revenue = sum(price × overage) per entitlement
margin  = ((revenue - cost) / revenue) × 100

Plan subscription revenue (flat fees) is not included in the local snapshot — that requires Cloud billing data. The local snapshot reflects usage-based margin only.

policy.customerMarginSnapshot()​

Returns a live margin breakdown for a specific customer based on their current meters.

const snapshot = await policy.customerMarginSnapshot('user_abc');

Return shape:

{
  revenue: number,  // total overage revenue generated (in runes)
  cost:    number,  // total cost incurred (in runes)
  margin:  number,  // ((revenue - cost) / revenue) * 100, or -100 if no revenue
  entitlements: {
    [entitlement: string]: {
      cost:    number,
      revenue: number,
      margin:  number | null  // null if no revenue on this entitlement
    }
  }
}
const snap = await policy.customerMarginSnapshot('user_abc');

console.log(`Revenue: $${snap.revenue.toFixed(4)}`);
console.log(`Cost:    $${snap.cost.toFixed(4)}`);
console.log(`Margin:  ${snap.margin.toFixed(1)}%`);

// Per-entitlement breakdown
for (const [name, ent] of Object.entries(snap.entitlements)) {
  console.log(`${name}: ${ent.margin?.toFixed(1) ?? 'N/A'}%`);
}

This is a local, in-process snapshot. It reflects the current meter state in the running policy instance, not the full billing period.

policy.marginSnapshot()​

Projects margin for a plan given hypothetical entitlement values. Use this for pricing decisions, plan design, and margin calculators — before any real customer data exists.

marginSnapshot(
  plan:         string,
  entitlements: Map<string, unknown>
): Promise<Map<string, unknown> | null>

The entitlements map accepts per-entitlement values in one of two forms:

Simple value — just the metered amount:

const projection = await policy.marginSnapshot('growth', new Map([
  ['chat_input',  800000],
  ['chat_output', 150000],
]));

Detailed map — with explicit credit and limit:

const projection = await policy.marginSnapshot('growth', new Map([
  ['chat_input', { meter: 800000, credit: 'sonnet_input', limit: 500000 }],
]));

When a plan is specified, Limitr resolves the credit and limit from the plan's entitlement definition automatically if not provided. The projection is scaled to the plan period by default — if an entitlement resets daily, Limitr scales it to the monthly equivalent for a monthly plan.

// {
//   revenue: ...,
//   cost: ...,
//   margin: ...,
//   entitlements: { chat_input: {...}, chat_output: {...} }
// }

Getting margin right​

The snapshot is only as accurate as your overhead_cost values. A few things to be aware of:

Abstract credits don't contribute to margin. Only discrete credits with overhead_cost defined factor into cost calculations. If an entitlement's limit is denominated in an abstract credit, it won't appear in the margin breakdown.

Margin is on overage only for soft limits. The plan's included allocation is assumed to be covered by the subscription fee. Only consumption above the soft limit generates overage revenue in the local snapshot.

Hard-limit entitlements generate no revenue in the snapshot. Because hard limits block overage, there's no overage billing — their cost is your cost of providing the included allocation.

Use marginSnapshot() to model the revenue implications of a pricing change before shipping it. Use customerMarginSnapshot() to monitor which customers are margin-negative in production.

Last updated on