Agent billing builds on the same meter, product, and Merchant-of-Record engine as the rest of Macropay. You get tax, dunning, and dispute handling for free — agents just add the attribution, margin, and ROI layer on top.
What is an agent
An agent is a named entity in your organization that work and money attach to. You create one withPOST /v1/agents, giving it a name, an optional external_id (your own identifier, for idempotent linking), and an optional description. Each agent carries a status:
Create an agent
The three billing models
The same agent can be billed on more than one axis. Pick the model that matches how your customer perceives value.Usage
Bill on LLM tokens consumed. Best when cost scales directly with model spend and customers expect metered pricing.
Activity
Bill per action the agent takes — a message sent, a tool call, a document processed. Best for predictable per-task pricing.
Outcome
Bill per result delivered — a resolved ticket, a booked meeting, a closed deal. Best when you sell the outcome, not the effort.
When to use each
| Model | You bill on | Reach for it when | Reported via |
|---|---|---|---|
| Usage | Tokens (input + output) | Your cost tracks the model meter and customers think in tokens or credits. | AI proxy at /ai/v1 |
| Activity | Actions taken | The unit of work is discrete and uniform, and value is roughly per-action. | Activity signals |
| Outcome | Results delivered | You can verify the result and customers will pay for the win, not the attempt. | Outcome signals |
Building blocks
Signals API
Report what an agent did (activity) and achieved (outcome) via
POST /v1/signals. These feed both activity/outcome billing and ROI.Value receipts
A certified ROI statement per agent — time saved, cost avoided, revenue generated, risk avoided — split into verified vs. reported value.
Agentic margin
Billed revenue minus AI cost (COGS) per agent, with a margin floor that flags agents quietly running you into the red.
SDK
Drop-in Python and TypeScript instrumentation — bind an agent once, then emit signals, record tool cost, and read margin in one-liners.
How costs get attributed
Two cost sources fold into an agent’s margin automatically:- LLM cost — when an agent’s calls route through the Macropay AI proxy at
/ai/v1using an agent-bound proxy key, every request’s token cost is captured and attributed with zero extra code. - Non-LLM cost (COGS) — tool calls, third-party APIs, and human-in-the-loop time are reported with
POST /v1/agents/{id}/costs(or the SDK’srecord_cost), so margin reflects true cost of delivery.
Get started
1
Create the agent
Register the agent with
POST /v1/agents. Keep the returned id (or set your own external_id) — it’s the key everything attributes to.2
3
See margin and ROI
Read agentic margin with
GET /v1/agents/{id}/margin and the certified ROI with GET /v1/agents/{id}/value-receipt, or explore both in the Macropay dashboard.Read the value receipt
Signals require a customer (
customer_id or external_customer_id) — billing always rolls up to an account. Outcomes are idempotent on external_id, so retries won’t double-count.FAQ
When should I bill on outcomes vs. tokens? Bill on tokens when your cost scales with model spend and the customer reasons in usage — it’s the safest floor because it always covers COGS. Bill on outcomes when you can verify the result (a booked meeting, a resolved ticket, a closed deal) and the customer is buying that result rather than the effort behind it. Outcome pricing captures the value you create instead of just your cost; the value receipt is what lets you defend the higher price. Do agents require the AI proxy? No. The AI proxy at/ai/v1 is the easiest way to capture LLM cost — point an agent-bound proxy key at it and token cost is attributed automatically. But you can run agent billing without it: report non-LLM COGS with POST /v1/agents/{id}/costs and bill on activity or outcome signals directly. The proxy is recommended, not mandatory.
How is agentic margin computed?
Margin is billed revenue minus AI cost (COGS) for an agent over a period, returned by GET /v1/agents/{id}/margin as revenue_cents, cost_cents, margin_cents, and margin_pct, broken down by_model. Revenue comes from the agent’s metered charges; cost comes from proxy token spend plus any recorded non-LLM COGS. A low_margin flag trips when margin_pct falls below the configured margin_floor_pct. See Agentic margin.
What is a value receipt?
A value receipt is a certified ROI statement Macropay computes per agent from its signals and cost — covering human-value-equivalent, time saved, cost savings, revenue generated, and risk avoided. You supply the assumptions (e.g. minutes saved per action, an hourly rate) and the engine produces the numbers, splitting outcome value into verified (confirmed by a trusted source) and reported (still self-attested). See Value receipts.
Can one agent use more than one billing model?
Yes. A single agent can bill usage on tokens, activity on actions, and outcomes on results at the same time — each axis is just a different meter and price scoped to the same agent_id. Margin and ROI net all of them together.
Next steps
Bill for LLM inference
Resell models through one URL and capture token cost automatically.
Cost Insights
See true per-agent and per-customer margin once cost sits next to revenue.
AI billing guide
Wire a meter, attach a price, and turn usage into invoices end-to-end.
AI SaaS use case
See how agent products put usage, activity, and outcome billing together.