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 MarginFront 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 — whatever 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 belongs to exactly one agent. 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.

​
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 (upcoming, active, ended). 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 (draft, open, paid, etc.), and a due date. See invoices.md.

​
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. That’s because 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 — e.g., 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.