Skip to main content

​
Core Concepts

MarginFront watches what your AI agents do, tracks what it costs you, and bills your customers. That’s it. Everything below is just naming the moving parts.

​
The building blocks

​
1. Agent

Your AI product. The thing that does work for your customers. A customer support bot is one agent. A research assistant is another. A document analyzer is a third. If you only sell one product, you have one agent. If you sell three products that price differently, you have three agents. Each agent has a code (a short handle you pick, like cs-bot or research-v2). You use this code when logging usage events — it tells MarginFront which product did the work. You create agents in the dashboard.

​
2. Customer

Who you’re billing. One of YOUR end users or companies. Each customer has an externalId — the user ID from your own system (like acme-001 or user_847). This is how MarginFront connects usage events to the right customer without you having to memorize MarginFront’s internal UUIDs. You can create customers through the dashboard, the API, the SDK, or the MCP tool.

​
3. Signal

What you measure. A deliverable or outcome your agent produces. Good signals (things your customer cares about):
  • messages — messages sent by a chatbot
  • reports-generated — full reports produced
  • pages-processed — document pages analyzed
Bad signals (internal details your customer doesn’t care about):
  • gpt-4o-call — that’s an internal cost, not a deliverable
  • api-requests — too technical, doesn’t map to value
Signals are what customers see on their invoices. They’re the answer to “what am I paying for?” You create signals in the dashboard, and each signal belongs to one agent.

​
4. Event

A record that something happened. This is the core data type — everything else is built from events. An event says: “Agent cs-bot sent 1 message for customer acme-001 using gpt-4o from openai, consuming 523 input tokens and 117 output tokens.” You log events by calling POST /v1/usage/record (or mf.usage.record() with the SDK). This is the endpoint your code calls all day, every day once you’re live. Everything else — costs, revenue, invoices, margins — is calculated from these events.

​
5. Service Costs

Calculated automatically. You don’t set these. When you log an event with a model and provider (like gpt-4o from openai), MarginFront looks up the token pricing in its built-in table of 300+ LLM models. It multiplies your input tokens by the input price, your output tokens by the output price, and stores the result as the service cost for that event. Your customers never see service costs. They’re for YOUR margin dashboard — so you can answer “how much did it actually cost me to serve this customer this month?” If MarginFront doesn’t recognize the model you sent, the event still saves — but with cost = null (not zero, not dropped). You can map the unknown model to a known one in the dashboard, and MarginFront backfills the cost retroactively. Events are never thrown away.

​
6. Pricing Plan

Turns your costs into prices. This is where you decide what to charge. A pricing plan sets the rate per unit of each signal. “I charge 0.10permessage"or"0.10 per message" or "2.00 per report.” Think of it like the “Starter Plan” or “Pro Plan” you’d show on your pricing page. Created in the dashboard, tied to an agent.

​
7. Subscription

Ties a customer to an agent through a pricing plan. “Starting April 1, bill Acme Inc for the cs-bot using the Starter Plan, on a monthly billing cycle.” Without a subscription, MarginFront still tracks costs (what things cost you), but it can’t calculate revenue (what you charge the customer) or generate invoices.

​
8. Invoice

Auto-generated at the end of each billing cycle from a subscription’s usage. Shows line items per signal with quantity and price. Example: “Messages: 150 x 0.10=0.10 = 15.00.” The customer sees what they used and what they owe. You see what it cost you, what you charged, and the margin.

​
9. API Key

Your credential for talking to MarginFront’s API. Starts with mf_sk_ (secret key — server-side only, full access). The API key identifies your organization — you never need to pass an org ID in your requests. Created in the dashboard under Developer Zone > API Keys. Never put your secret key in frontend code or commit it to git.

​
The metric vs service cost mental model

Signals are what your CUSTOMER sees. Service costs are what YOU see. A customer sees their invoice: Messages: 150 x $0.10 = $15.00 You see your margin dashboard: Messages: 150 events, $2.34 LLM cost, $15.00 revenue, 84% margin Same events, two perspectives. Signals face outward (billing). Service costs face inward (profitability).

​
Pricing Strategy Types

A pricing strategy is one specific rule inside a pricing plan. Every strategy has a charge type that decides WHEN the customer is billed and a pricing model that decides HOW the number is calculated.

​
Charge types (when to bill)

There are four charge types. Each answers a different question.
Charge typeWhen it firesExample
usageEvery time an event comes in. Priced per unit of a signal.”Charge $0.10 per message, after it’s sent.”
recurringOnce per billing cycle, whether the customer used anything.”Charge $99 on the first of every month.”
seat_basedOnce per billing cycle, priced by seatsCount on the sub.”Charge 10perseatpermonth.Customerhas5seats:10 per seat per month. Customer has 5 seats: 50/month.”
onetimeOnce, on the subscription start date. Never again.”Charge $500 setup fee when the customer signs up.”

​
Pricing models (how to calculate)

Usage strategies route through one of four pricing models.
  • flat Simple rate per unit. quantity × rate.
  • graduated Tiered with progressive rates. Units 1 to 10 at one rate, 11 to 50 at another, 51+ at a third. Each unit pays the rate for ITS tier.
  • volume Tiered with one rate for all units. All units pay the rate of the tier the TOTAL quantity landed in.
  • credit_pool Flat fee for a pool of units. Per-unit overage after the pool is used up. Often called “commitment + burst.”

​
Per-window-aggregate billing

Usage strategies bill on the TOTAL quantity for the window, not per event. That means:
  • One event with quantity: 1500 bills identically to three events with quantity: 500 each.
  • MarginFront adds up all the events in the billing period, feeds the total through the pricing model, and produces one invoice line.
You never have to worry about “did I send too many events” from a billing math standpoint. More events just means more detail in the history. The total is what lands on the invoice.

​
Cost-only metrics

You can skip pricing entirely. If a signal has no pricing strategy linked to it, events still come in and cost still tracks, but the revenue contribution for that signal is zero (not unknown, not missing: explicitly zero). Useful for:
  • Tracking infrastructure costs you don’t pass through to customers.
  • Shadow-logging new signals you haven’t decided how to price yet.
  • Internal tool usage that’s part of your operating cost, not a line item.
The cost side still flows to your margin dashboard. The customer never sees the metric on their invoice.

​
The four labels of revenue

MarginFront reports four different dollar amounts for “revenue,” each answering a different question. They are NOT the same number. Know which one you’re looking at.

​
Agent-Earned

What your agents produced this period, at the pricing strategy rates. No fees, no proration. Formula: every usage event in the window, multiplied by the rate for its pricing strategy, summed up. Use it to spot activity trends early. Agent-Earned goes up the moment an event fires. No need to wait for invoices to finalize.

​
Revenue

The full formula. What the customer owed you for the period. Agent-Earned plus recurring fees plus seat fees plus onetime fees (all prorated if the subscription only partly overlapped the window). Use it for “what did we earn this month, invoiced or not.”

​
Billed

What you actually invoiced. Issued invoices, waiting on payment. Sum of every invoice with status issued or overdue that was dated in the window. Draft invoices don’t count here. Paid invoices don’t count here (those move to Collected). Use it for A/R tracking.

​
Collected

Cash landed. Invoices marked paid. Sum of every invoice with status paid that was dated in the window. Use it for cashflow.

​
Why four?

Because they answer different questions and they come out in that order:
  1. Agent does work. Agent-Earned goes up.
  2. Billing cycle ends. An invoice finalizes. Billed goes up.
  3. Customer pays. Collected goes up.
If Agent-Earned is strong but Billed is weak, something is wrong with invoice generation. If Billed is strong but Collected is weak, something is wrong with collections. Separating the four makes the hole in your pipe obvious.

​
Choosing your signal name and quantity

Before you write a single line of code, you have one decision to make: what unit do you want your customer to see on their invoice? That answer becomes your signal name. Everything else falls out of it. Four rules cover the whole thing:
  1. Fire one event per business outcome. When a report finishes, that’s ONE event. When a call ends, that’s ONE event. Not one per page, not one per minute, not one per token. MarginFront is not a streaming meter — it’s a “something happened” logger.
  2. The signal name IS the billing unit. Bill per page? Name it pages. Bill per report? Name it reports. Bill per minute? Name it minutes. Whatever word shows up on your invoice is what you type into signalName.
  3. quantity is the count of that billing unit for this one event. A 50-page report fired as pages has quantity: 50. The same report fired as reports has quantity: 1. Same LLM call underneath, same cost, different invoice line.
  4. Cost and revenue are decoupled. MarginFront calculates your cost from model + modelProvider + tokens automatically. Your revenue is quantity × your pricing plan rate. The gap is your margin.
Here’s the same Claude call — a 50-page market research report — billed three different ways depending on what you named the signal:
Signal nameQuantityRate per unitWhat the customer sees on the invoice
reports_generated1$50.00 per report”1 report × 50.00=50.00 = 50.00”
report_pages50$2.00 per page”50 pages × 2.00=2.00 = 100.00”
tokens_used15,000$0.01 per 1K”15,000 tokens × 0.01=0.01 = 0.15”
Same Claude call. Same underlying token cost. Three completely different invoices. The choice of signal name is the contract between “the agent did work” and “the customer gets billed this much for that work.”
Fire one event per outcome. Not one per page, not one per minute. This is the single easiest thing to get wrong. If your agent writes a 50-page report, send MarginFront ONE event with quantity: 50 — not 50 events with quantity: 1. The point of the quantity field is that you don’t have to loop. Looping would multiply your bill, flood your analytics, and burn API calls for no reason.
When in doubt, pick the signal name your customer would say out loud if you asked them “what am I paying for?” That word is the name. See Example 3 in Tracking Events for the exact code pattern, and the Signals API reference for the full signal API.

​
Setup sequence (the golden path)

Here’s the order things happen, from zero to fully working: 
1. Create Agent
      |
      v
2. Create Signal (tied to the agent)
      |
      v
3. Create Pricing Plan (optional -- skip if you only need cost tracking)
      |
      v
4. Link Plan to Agent (optional -- done automatically when you create the plan)
      |
      v
5. Create Customer
      |
      v
6. Create Subscription (optional -- ties customer + agent + plan together)
      |
      v
7. Send Events (the thing you do every day)
      |
      v
8. See it on the Dashboard (costs, revenue, margins, invoices)
Steps 3, 4, and 6 are optional. If you only care about tracking what your AI costs you (not what you charge your customers), skip them entirely. You can always add pricing plans and subscriptions later — nothing breaks without them.

​
Three integration paths

You can send events to MarginFront three different ways. Pick whichever fits your workflow. 
npm install @marginfront/sdk
Lives in your agent’s code. Sends usage events with automatic batching and retries. If MarginFront is down, events queue locally and retry — your agent never stalls. See the OpenAI recipe for a complete example.

​
REST API (any language)

Same event endpoint (POST /v1/usage/record), raw HTTP. Works from any language or platform — Python, Go, Ruby, curl, whatever. Pass your API key in the x-api-key header. See the Usage Events reference for the full field reference.

​
MCP (for AI coding assistants)

Same API, but your AI coding assistant (like Claude Code or Cursor) calls it for you. Useful for setting up agents, customers, and signals without leaving your editor. See the MCP Setup guide for details.

​
Next steps