Skip to main content

​
Glossary

Quick definitions of the words that show up throughout the MarginFront docs. If a term confuses you, start here.

​
Customer

One of your customers. A person, company, or account that uses your product and that you want to bill. Not a MarginFront customer. MarginFront doesn’t sell to your customers directly. You create a customer record in MarginFront so it knows who to track usage and bills for. Key fields: name, externalId (your internal ID for them), email. See customers.md.

​
Agent

The thing doing the work. An agent can be an AI agent, a microservice, a worker, a product, a Lambda function. Anything that produces billable activity. Every piece of usage in MarginFront is attributed to exactly one agent. You might have just one agent (if you sell one product), or many agents (if you sell multiple products that price differently). Key fields: name, agentCode (short unique handle you pick), description. See agents.md.

​
Signal (also called “metric”)

What you measure and bill on. A signal is the unit of work you’re charging for. Examples:
  • messages (messages sent by a chatbot)
  • pages_processed (documents analyzed)
  • minutes_transcoded (video minutes)
  • images_generated
Signals always belong to an agent. Each agent can have multiple signals. The signal’s shortName is what you reference when logging usage events. See signals.md.

​
Pricing plan

Defines how an agent charges for its work. Think “Starter Plan,” “Pro Plan,” “Enterprise Custom.” Each pricing plan can be linked to one or more agents. A customer subscribed to a plan gets billed according to that plan’s rules for anything they do with that agent. See pricing-plans.md.

​
Pricing strategy

The actual math inside a pricing plan. A plan is a container. A strategy is one specific rule inside it, like “charge 0.10permessage"or"charge0.10 per message" or "charge 99 per month.” Plans have one or more strategies; strategies do the actual price calculation. See pricing-strategies.md.

​
Subscription

Ties a customer to a pricing plan. Until a customer has a subscription, MarginFront doesn’t know how to charge them. A subscription has a start date, an optional end date, a billing cycle (monthly, yearly, custom), and a status (active, canceled, past_due, trialing). See subscriptions.md.

​
Usage event (also called “tracked event” or “signal event”)

A single measurement. “At this time, this customer used this agent to do this much of this thing.” You log a usage event every time your agent does work. MarginFront counts them up over the billing period and applies the customer’s pricing plan to produce an invoice. Logged via POST /v1/usage/record. See usage-events.md.

​
Invoice

A finalized bill. The document you send to a customer at the end of each billing period. MarginFront generates invoices automatically based on each customer’s subscription and logged usage. An invoice has line items (per signal, per agent), a total, a status (see below), and a due date. See invoices.md.

​
Invoice statuses

The state an invoice is in. MarginFront uses these seven:
  • draft: Still being built. Not yet shown to the customer.
  • pending: Created but waiting on a hand-off step (for example, waiting for a payment provider to confirm).
  • issued: Sent to the customer. Waiting on payment.
  • paid: Customer paid in full.
  • overdue: Issued but past the due date without payment.
  • void: Canceled. Shouldn’t be collected on. Never counted in revenue numbers.
  • refunded: Payment was reversed after the customer already paid.

​
Organization (“org”)

The top-level container in MarginFront. Every customer, agent, signal, plan, subscription, and invoice belongs to exactly one organization. When you sign up for MarginFront, you get an org. If you’re running a multi-tenant product, you’ll have one org per MarginFront account (not one per customer). Your customers go INSIDE your org as customer records. Org ID: a UUID identifying your MarginFront organization. You normally never need to pass this anywhere. The API key alone tells MarginFront which org you are. If you need to find your org ID for support or debugging, hit GET /v1/verify with your key and look at the organization.id field in the response. Every API key belongs to exactly one org.

​
API key

The secret that authenticates your code to MarginFront. Secret keys look like mf_sk_test_... or mf_sk_live_... (full access, backend only). Publishable keys look like mf_pk_test_... or mf_pk_live_... (read-only, safe in browser code). Goes in the x-api-key header of every request. See authentication.md for how to use and manage them.

​
externalId / agentCode / shortName

String-based handles that YOU pick for customers, agents, and signals. These let you reference MarginFront resources using IDs that are meaningful in YOUR system, instead of having to remember MarginFront’s internal UUIDs.
  • externalId your ID for a customer
  • agentCode your short code for an agent
  • shortName your short name for a signal (used in usage events)

​
UUID vs external ID: which should I use?

It depends on the endpoint:
  • CRUD endpoints (create, read, update, delete for customers, agents, signals, pricing plans, subscriptions) mostly use UUIDs (the internal id field) in URLs and foreign keys. When you create a subscription, you pass customerId, agentId, and planId as UUIDs.
  • Usage event logging (POST /v1/usage/record) uses the string handles instead: customerExternalId, agentCode, signalName. Usage events are high-volume and the string handles are more ergonomic than copying UUIDs around.
Both reference the same underlying records. They’re just different ways to look them up. See each resource’s docs for which fields it expects where.

​
LLM / Model

MarginFront has built-in cost lookups for many popular large language models (GPT-4o, Claude Sonnet, etc.). When you log a usage event from an LLM-powered agent, you include the model field so MarginFront can calculate the actual per-token cost. For non-LLM services, you can still include a model identifier (MarginFront treats it as a cost lookup key) or use quantity instead of tokens.

​
Billing cycle / Billing period

The time window an invoice covers. If a subscription has billingCycle: "monthly", MarginFront generates one invoice per calendar month covering all usage in that month. The “billing period” is one specific instance of the cycle. For example, April 1-30 is one billing period for a monthly subscription.

​
Net terms

Number of days a customer has to pay an invoice after it’s issued. Default is 30 (meaning “invoice due 30 days after it’s generated”). Usually set at the customer level or the subscription level.

​
Auto-create

A convenience feature. If you log a usage event for a customerExternalId or agentCode that MarginFront has never seen, it auto-creates a minimal customer or agent record using that ID. Great for prototyping. Easy to miss if you make a typo. Consider it a “helpful on-the-fly” behavior rather than a replacement for explicit setup.

​
Model

The identifier for the AI model or service that did the work. Pass whatever your provider SDK returned. response.model from OpenAI/Anthropic, or the service SKU for non-LLM tools. Examples: "gpt-4o", "claude-sonnet-4-6", "twilio-sms", "textract-standard". Case-insensitive, whitespace trimmed. Required on every usage event.

​
Model Provider

The name of the company that runs the model, in lowercase. Examples: "openai", "anthropic", "google", "twilio", "aws". Required because different providers can have models with identical names. Without this field, MarginFront can’t tell which pricing table to look in.

​
Needs Cost Backfill

An event that was stored successfully but doesn’t have a cost yet because the model+provider combination wasn’t in the pricing table. These events show up in the dashboard under “Needs attention” and can be mapped to a known model with one click. Once mapped, cost is calculated retroactively and all future events with that model auto-resolve.

​
Missing Volume Data

An event that was stored successfully but didn’t carry the volume numbers needed to calculate cost. For an LLM event, that means inputTokens or outputTokens was missing. For a non-LLM event, that means quantity was missing. The event still counts in event-count totals but has no cost. Fix it by replaying the event with the missing field filled in, or leave it if you only needed the timestamp.

​
Cost

How much MarginFront’s built-in pricing table says the work cost you to deliver. Calculated from the event’s model, provider, and token counts (or quantity for non-LLM work). Only what MarginFront could match against its own pricing table counts. Events with an unknown model contribute zero until you map the model. This is the number you look at on your margin dashboard. Your customers never see it.

​
Agent-Earned

The first of four revenue numbers. Pure activity: what your agents produced in a time window, priced against your pricing strategies. No subscription fees, no proration, no invoices involved. It’s the earliest signal of “did work happen this week that we’ll eventually bill for?” Formula: for every usage event in the window, multiply quantity times the pricing strategy rate. Add them up. Useful for: spotting usage trends fast, before invoices finalize.

​
Revenue

The second of four revenue numbers. The full formula: Agent-Earned plus the recurring fees, seat fees, and onetime fees for any active subscription during the window. Prorated if the subscription only partially overlaps the window. Useful for: “what did the customer owe us for this window?”

​
Billed

The third of four revenue numbers. The total of every invoice dated in the window that has been sent out (status issued or overdue). Draft invoices don’t count. Void invoices don’t count. Paid invoices don’t count here either (they count in Collected). Useful for: “how much did we actually invoice this period?”

​
Collected

The fourth of four revenue numbers. The total of every invoice dated in the window that has been paid in full (status paid). A proxy for cash landed. Useful for: “how much money actually came in this period?”

​
Margin

Revenue minus cost. Every one of the four revenue numbers (Agent-Earned, Revenue, Billed, Collected) has its own margin. You’ll see “Agent-Earned Margin,” “Billed Margin,” “Collected Margin” on the dashboard. Margin percent is margin divided by revenue. When revenue is zero, the percent isn’t shown (it would be meaningless). The dashboard shows a dash instead.

​
MRR (Monthly Recurring Revenue)

Your monthly run rate. MarginFront calculates MRR three different ways:
  • MRR (the default): the total of invoices sent out last complete calendar month. Backward-looking. Answers “what did we actually bill last month?”
  • Run-Rate MRR: the trajectory based on the last 30 days of activity plus any committed recurring fees, normalized to a month. Forward-looking. Answers “if the last 30 days kept going, what would we bill per month?”
  • Committed MRR: just the contractual floor. Minimum commitments on every active subscription, no actual usage included. Answers “what do we bill for sure, no matter what customers do this month?”
Multiply any of these by 12 to get ARR (annual run rate).

​
Invoice date

The date stamped on the invoice when it’s sent out. MarginFront uses this date (not createdAt, not dueDate, not the billing period) to decide which window an invoice falls into for Billed and Collected numbers.

​
Never-drop-events rule

MarginFront never throws away a usage event, even if something is wrong with it. If the model isn’t recognized, the event still stores (with cost pending backfill). If volume data is missing, the event still stores (flagged as missing). If the pricing strategy doesn’t match, the event still stores. Your data is safe. You fix issues in the dashboard and MarginFront backfills.

​
Default quantity

If a usage event doesn’t specify quantity, MarginFront stores it as 1. Most discrete events (one SMS, one API call) don’t need to pass quantity. The default kicks in AFTER validation, so non-LLM events that didn’t send quantity still get flagged as missing volume data. The default is a storage convenience, not a way to skip validation.