End-user credits: charge your users for agent spend on camelRun

View as Markdown · Docs index for coding agents

End-user credits let you charge your own users for what their agents spend. camelRun keeps a balance for each person your app serves, gives each a daily free allowance per part of your product, enforces both on every model call, and tells you when someone runs low or runs out. You keep the money side: your payment provider, your pricing page, your emails. After a payment, you tell camelRun "add $10 to this person".

Everything a person causes counts against one balance: every agent that acts for them, their stateless runs, transcriptions, images, web searches and the rest. You still pay camelRun for raw usage as before (see pricing). End-user balances are your ledger of your users, and camelRun never moves money for them.

The model

• End user: the subject of an agent (set when you upsert it, see multi-user apps) or of a call (POST /v1/runs, /v1/transcriptions, /v1/images). An agent's sub-agents act for its subject too. Work with no subject is not metered: you pay for it, as today.
• Bucket: the part of your product that spends, such as builder or bot:42. An agent spends from its bucket; a stateless run or call names its own. A prompt sent with your API key (POST /v1/agents/{id}/prompt) may name another; an agent's own token can't. A run that names none (a schedule's, a sub-agent's notice, a channel's message, a voice session's ask_agent, or one you send without) spends from the agent's bucket, else the bucket your latest run of the agent named, else default.
• Daily allowance: free spend per bucket per UTC day, spent first. Set it by bucket name, by prefix ("bot:*") or for every bucket ("*"). A bucket takes its own name, else the longest prefix it starts with, else *. You can override allowances per person. Allowances count raw cost: what the call costs you.
• Balance: paid credit, spent once the allowance is used. Grants (after a payment) add to it; refunds and adjustments take from it.
• Markup: added to the raw cost of paid spend before it is charged (markupBps: 2500 is +25%). The ledger records both.
• Daily limit: the most a person's paid spend may be per UTC day, for everyone or per person.
• Bucket limits: the most one bucket may charge a person's balance per UTC day, keyed like allowances, for everyone or per person. A bot at "bot:*": 2_000_000 spends its allowance, then at most $2 of the balance a day, however much the person holds. At 0 it spends its allowance only. To list the only buckets that may spend paid credit, give "*": 0 and a limit for each: { "*": 0, builder: 20_000_000, "bot:*": 2_000_000 }. No other bucket, default included, then ever charges anyone's balance.

All amounts are integer micro-USD: 1 USD = 1,000,000.

A call costs a person what it cost you. On camelRun's keys that is what you are charged for it: the provider's price, plus the cost of funding OpenRouter credit on OpenRouter calls (about 5.5%). On your own keys it is the provider's reported cost, else the catalog's price for its tokens (cache reads and writes included), as usage.recorded shows. The markup is on top. A model with no price (one of your own models declared without pricing) is never free to them: it is charged at the catalog's price for the model, else a mid-range price ($3 in, $15 out per million tokens). Declare its pricing to charge your own.

Changing an allowance or a limit never resets what was spent today. Spend is kept per day and bucket, and the allowance is only the cap: raise a bucket from $40 to $60 mid-day and the person has $20 more, not $60.

Turn it on

import { Agents } from "@camelai/run";
const agents = new Agents();

await agents.endUsers.configure({
  enabled: true,
  allowances: { builder: 50_000_000, "bot:*": 1_000_000 }, // $50 a day for the builder, $1 a day per bot
  markupBps: 2_500,                                          // paid spend at cost +25%
  dailyLimit: 20_000_000,                                    // at most $20 of paid spend a day
  bucketLimits: { "bot:*": 2_000_000 },                      // and at most $2 of it per bot
  lowBalance: 2_000_000,                                     // end_user.balance.low below $2
  allowanceWarningPercent: 80,                               // end_user.allowance.low at 80% of a bucket's allowance
});

The REST call is PUT /v1/end-user-settings. Fields left out keep their values, but allowances and bucketLimits, when sent, replace the whole map. To change some keys and keep the rest, use PATCH /v1/end-user-settings (endUsers.amend, Python end_users.amend): only what you send changes, maps merge key by key, and null removes a key. A person's own overrides merge the same way (endUsers.update).

Several writers can change the settings at once (each server of yours as it starts, an admin tool, a script). Each write changes only the fields it sends, and a PATCH merges its keys into the map as it stands, so writes to different fields or keys all keep their changes. Of two writes to the same field or key, the later wins. Give each writer its own fields and keys and have it PATCH only those.

Example: pay as you go

A person buys credit with Stripe; their builder agent and their bots spend it.

// 1. Their agents act for them, each from its bucket.
const builder = await agents.upsert(`builder-${user.id}`, { subject: user.id, bucket: "builder", definition: BUILDER });
const helper = await agents.upsert(`bot-${botId}`, { subject: user.id, bucket: `bot:${botId}`, definition: BOT });

// 2. One-off model calls in their bot's code spend from the same bucket.
const answer = await agents.run({ input: prompt, subject: user.id, bucket: `bot:${botId}` });

// 3. A payment lands: credit it, once per payment (a retried webhook posts nothing twice).
app.post("/stripe/webhook", async (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, req.headers["stripe-signature"], secret);
  if (event.type === "payment_intent.succeeded") {
    const payment = event.data.object;
    await agents.endUsers.grant(payment.metadata.userId, { amount: payment.amount * 10_000, key: payment.id, reference: `Stripe ${payment.id}` });
  }
  res.sendStatus(200);
});

// 4. Their credit page: where they stand, what they bought, and what their credit went to each day.
const person = await agents.endUsers.get(user.id, { buckets: ["builder"] });
// person.balance, person.available, person.today.buckets[0].allowanceLeft
const purchases = await agents.endUsers.ledger(user.id, { kind: ["grant", "refund", "adjustment"], limit: 20 });
const { days, next } = await agents.endUsers.days(user.id, { limit: 7 });
// days[0]: { day: "…", freeRaw, paidCharged, writtenOff, granted, refunded, adjusted, entries, buckets: [{ bucket: "bot:42", freeRaw, paidCharged, writtenOff }] }

In Python:

await agents.end_users.grant(user_id, amount=amount_cents * 10_000, key=payment_id, reference=f"Stripe {payment_id}")
person = await agents.end_users.get(user_id, buckets=["builder"])
purchases = await agents.end_users.ledger(user_id, kind=["grant", "refund", "adjustment"], limit=20)
days = await agents.end_users.days(user_id, limit=7)

A credit page reads no usage rows: the ledger's kind filter leaves them out, and days gives each UTC day's totals by bucket in one request.

For a refund you make in Stripe, endUsers.refund(id, { amount, key }) takes the credit back. It can take at most the balance that calls in flight don't hold; past that it is a 409 INSUFFICIENT_BALANCE, with refundable. For anything else, endUsers.adjust(id, { amount, key }) takes a signed amount. Grants, refunds and adjustments are idempotent by key: the same key and entry again returns the first, and the same key for a different entry is a 409.

To charge a saved card when someone runs low, see auto top-up.

When a person runs out

camelRun holds credit for each model call before making it: its input and up to 2,048 tokens of output, from the bucket's allowance first, then the balance. A longer reply holds more as it streams. Holds are taken one at a time per person, so calls in parallel (sub-agents, several of their agents at once) never each see the whole balance.

When nothing more can be held:

• A new run is refused with 402 and code END_USER_CREDIT, with endUser, bucket and reason in the body. The SDKs throw AgentError with the same fields (reason, bucket, endUser; Python end_user).
• A queued run refused as it starts fails with code end_user_credit, reason, bucket and endUser.
• A run already going stops where the credit ends, even mid-reply. What streamed is kept, and the run fails with code end_user_credit, stopped: "spend_limit", limit: "end_user", a reason, the bucket and the endUser. It is never retried.
• The run.failed webhook carries code, limit, reason, bucket and endUser too, and voice.session.ended its endUserReason and bucket.
• Transcriptions, speech and images are refused before they are made, with the same 402.

reason is one of:

endUserCredit (Python end_user_credit) reads these from a thrown error, a failed run or its error, so one place handles every path:

import { endUserCredit } from "@camelai/run";

try {
  const run = await agent.run(text, { throwOnError: false });
  const credit = endUserCredit(run);
  if (credit) notify(user, credit.reason);
} catch (error) {
  const credit = endUserCredit(error); // a 402 at submit
  if (!credit) throw error;
  notify(user, credit.reason);
}

function notify(user: string, reason?: string) {
  // "daily_limit" | "bucket_limit" | "balance"; a reason added later: a credit refusal of no particular kind.
}

Branch on code and reason, never on the message: its words are for people and may change.

Costs past a call's hold are written off

Usage never takes a balance below zero, and never takes paid spend past the daily limit or a bucket's limit. A call can still cost more than it held:

• output a provider bills without streaming it (hidden reasoning tokens);
• what streams while the last credit check is answered (milliseconds of output);
• the gap between the input estimate and the real input (a provider cache that expired, a provider's own price at the time);
• a call cut off by a failure: its hold lapses after 10 minutes, and if the provider reports its cost later, it is settled then.

When it settles, the person is charged at most what is left for it: the balance, the daily limit and the bucket's limit, less what their other calls in flight hold. The rest is written off. You bear it (your camelRun usage is the call's full cost, as always), and it is never charged to the person later, even after they buy credit. Each usage entry shows it as writtenOff, GET /v1/end-users/{id} totals it per bucket for today (today.buckets[].writtenOff), and GET /v1/end-users/{id}/days per bucket and day, all in raw micro-USD. The limit that capped the charge fires end_user.credit.exhausted as a refused call would, and the person's next call is refused.

A cost corrected down later takes back the write-off first, then refunds what the balance paid, then the allowance. A cost corrected up is capped the same way, by the limits of the day the call began and the balance as it is then.

Webhooks

Subscribe an endpoint (POST /v1/webhooks, see webhooks) to:

They are signed and retried like every webhook, and written in the same transaction as the change that caused them.

When balance events fire

end_user.balance.low and end_user.credit.exhausted with reason: "balance" each carry a cause: what moved the balance.

"cause": {
  "kind": "usage",       // usage | usage_correction | grant | refund | adjustment | refusal | threshold_changed
  "entryId": 1234,       // the ledger entry; none for refusal and threshold_changed
  "entryKey": "dp_123",  // your key, for grant, refund and adjustment
  "requestId": "…",      // usage: the run's request, when there is one
  "bucket": "bot:42"
}

• usage_correction is a call's cost posted again, corrected: a provider's final figure, which can come long after the call.
• refusal is a call refused with no balance left. It has no ledger entry.
• A person's entry ids grow, so entryId puts their events in order, which delivery may not.

The rules:

• balance.low fires on a debit (usage or a negative adjustment) that takes the balance from at or above the threshold to below it. Staying below fires nothing more until one of the next rules applies.
• credit.exhausted (balance) fires on a debit that takes the balance from above zero to zero or below, and on a call refused with no balance left (cause.kind: "refusal"), once until the balance is back above zero or re-armed.
• A grant or positive adjustment that leaves the balance short re-arms the event: the next debit fires it again. With a $10 threshold, a $5 top-up that leaves someone at $6 makes their next debit fire balance.low again. A grant that leaves someone at or below zero makes their next debit or refused call fire credit.exhausted again.
• Any move that leaves the balance past the line (at or above the threshold, above zero) resets the event, including a cost corrected down: the next crossing fires.
• Setting a threshold fires balance.low once, with cause.kind: "threshold_changed", for each person under it who hasn't been told since they were last above it (or was re-armed since). A person's own threshold applies to them alone. Your account-wide lowBalance applies to everyone without their own who has ever been credited. Setting the same value again fires nothing.
• Refunds are silent. A refund fires neither event (no one should be topped up because you gave money back), and counts as told for each line the balance is short of, so neither fires until a grant or a positive adjustment.
• Someone never credited (who only spends free allowances) isn't re-armed by anything, and your account-wide threshold never tells them their balance is low.

The ledger

Every movement of a person's money is an entry, newest first:

A call whose cost is corrected later has another usage entry for the difference. balanceAfter is the balance after each entry.

Narrow it with kind (any of grant, refund, adjustment, usage; comma-separated in the API), from and to (a time range on createdAt, to exclusive: epoch milliseconds, a UTC day or an ISO 8601 time), bucket, and moved=true (only entries that moved the balance, leaving out usage the allowance paid in full). They combine with each other and with before and limit.

Per day

GET /v1/end-users/{id}/days (endUsers.days(id, { from, to, bucket, limit })) gives a person's UTC days, newest first, limit days a page (default 31, at most 100; pass next as to for the next page). from and to are UTC days (YYYY-MM-DD, to exclusive), at most 366 apart, by default the 366 days up to today. Days with no spend and no entries are left out. bucket keeps that bucket's spend alone, without entries (entries belong to no bucket).

A call counts on the UTC day it began (its usage entry's metadata.day), so near midnight that can differ from its entry's createdAt. An entry you post counts on the day you posted it.

Units

Amounts are integer micro-USD. Some are raw cost (what a call cost you); others are charged, in the balance's units (raw cost with your markup).

A bucket's held today adds the allowance's part of holds (raw) to the balance's (charged). Read available and allowanceLeft for what is left.

API

bucket is taken by agent upserts and configuration, prompts sent with your API key, POST /v1/runs, /v1/transcriptions and /v1/images.