Documentation · App Builder
Billing
An app's users pay you, the organisation that owns the app. They buy credits or subscribe to plans through Stripe; the money goes to your organisation's Stripe account and WebRobot keeps a platform fee. The work the app does with credits (agent runs, chat messages, instances, events) is priced in spec.billing. The field list is in the reference.
This is separate from what your organisation pays WebRobot for the platform's usage.
Billing modes
billing:
modes: [credits, subscription]
currency: eur
signupCredits: 20
costs:
"agent:analyst": 5
packs:
- { key: small, credits: 100, price: 9, label: "100 credits" }
plans:
- { key: pro, price: 29, interval: month, credits: 400, label: Pro }
modes lists one or more of free, credits, subscription, per_transaction. Validation checks that they make sense:
freecannot be combined with another mode.creditsneeds a way to get credits: packs, plans with credits, orsignupCredits.subscriptionneeds plans.
What users are charged comes from costs, not from modes: an app with no costs charges nothing.
per_transaction, transactionFeePct, sellers, revenueShare, and the plan fields includes, creditsReset, transactionFeePct and roles, and the pack field unlocks are accepted by the schema but not applied by the runtime yet.
Credits
Each user of the app has a credit balance. Every movement is written to the user's ledger with a reason, and each movement is applied once (a retried payment or settlement never counts twice).
Users get credits from:
signupCredits, once, when they first sign in;- packs they buy, and the credits of a plan on each paid period;
- an admin's top-up by hand (1–100,000 credits at a time, from the
adminview).
Credits are spent by:
| What | Price | When |
|---|---|---|
| A run from the form | costs["agent:<key>"], else costs.run | Held at the start, settled at the end. See Runs. |
| A chat message | costs["agent:<key>"] (the number, or its estimate) | Taken when the message is sent, returned if no reply comes. Not charged when the organisation's chat server answers during service hours. |
| A template instance run | the template's cost.perRun | Taken at the start, returned if the run produces no result. |
| An event | a trigger's charge | Once per event. |
Without enough credits, the action is refused with 402 "not enough credits"; the answer carries needed and balance.
Costs
A cost is a number of credits, or an object:
| Form | Meaning |
|---|---|
5 | A fixed price. |
{estimate: 20, metered: true} | Pay per use: 20 credits held, the real usage charged at the end. |
{requiresPlan: pro, …} | Only users with the plan pro may run it (402 "needs the plan pro"). |
{perUnit: {field, credits, min, max}} | The price follows a number field of the form: credits × value, rounded up, then kept within min and max. |
costs:
"agent:survey":
perUnit: { field: hectares, credits: 2, min: 10, max: 500 }
perUnit must name a number field of the form, and cannot be metered as well.
Admins are not charged
Users with an admin role (assigned from the app's admin emails) run, chat and use the app for free: nothing is held, the run is marked free. An admin running their own template instance by hand pays nothing.
How a run is charged
- Hold. At the start, the estimate (or the fixed price) is taken from the balance. Without enough credits the run does not start.
- Start fails. The hold is returned at once.
- Run ends without a report. The whole hold is returned.
- Run ends with a report. The run is settled once:
- fixed price: the hold is the price;
- metered price: the real usage is priced (below). If it is less than the hold, the difference is returned; if more, the difference is taken.
When the usage is above the estimate and the balance cannot cover it:
- with
metering.allowNegative: true, the balance goes below zero; - otherwise, the runtime takes what the balance has; the rest is recorded on the run as unpaid.
The run page shows the credits charged, "pay per use: what the run really consumed" for a metered run, and the credits beyond the balance when there are any.
Pay-per-use metering
A cost with metered: true is settled on what the run really used, with billing.metering:
billing:
modes: [credits]
metering: { creditEur: 0.01, markupPct: 50 }
costs:
"agent:research": { estimate: 40, metered: true }
packs:
- { key: p500, credits: 500, price: 5 }
The price of a run:
cost = LLM tokens × the model's rate + compute (whole hours started) × the hourly VM rate
price = cost × (1 + markupPct / 100)
credits = price / creditEur, rounded up
| Field | Meaning | Default |
|---|---|---|
creditEur | The value of one credit in euro | 0.01 |
markupPct | Your margin on the cost | 50 |
drivers | What is priced: llm_tokens and compute (vm counts as compute) | both |
allowNegative | Let the balance go below zero when usage is above the estimate | false |
- Tokens are priced at the platform's rate card for the model's family (Opus, Sonnet, Haiku), cache reads and writes included. An unknown model is priced as the most expensive family.
- Compute counts the run's minutes rounded up to whole hours, at least one hour.
browser,proxyandstoragedrivers are accepted but not priced.- If the platform recorded no token usage for the run, the estimate is charged.
Each metered run keeps its measurement: tokens, model, minutes, cost and credits.
Metering applies to form runs. A chat message costs its fixed price or estimate, without settlement.
Credits charged by a trigger
A trigger with charge takes credits from the event's user: a success fee when a case is approved, a fee per contact.
triggers:
- key: success_fee
on: { approval: offer, decision: approved }
charge: { credits: 50, reason: "Success fee" }
credits1–100,000;reason(up to 120 characters) is the ledger line, default the trigger's key.- Charged once per event (the same record at the same update is charged once).
- The event needs a user: a record, an approval, a payment or a date. A
cronorwebhooktrigger cannot charge. - The charge is taken even when it takes the balance below zero.
Packs and plans
Packs are one-off purchases that add credits.
| Field | Meaning |
|---|---|
key | Its name. |
price | In billing.currency (default eur). |
credits | Credits added when paid. |
label | What the user sees. |
Plans are subscriptions.
| Field | Meaning |
|---|---|
key, price, label | As for packs. |
interval | month or year. |
credits | Credits added on every paid invoice. |
While a subscription is active, the user holds the plan. Plans unlock what the manifest gates by plan: a cost's requiresPlan, a field or option's gatedBy, a limit's plans, a data view's teaser (preview.unlessPlan).
Stripe
Enabling payments
Payments go to your organisation's Stripe Connect account (Express). An admin of the organisation enables payments in App Studio: the console creates the account on the first try and opens Stripe's onboarding. The account can take payments once Stripe has enabled card payments and transfers on it.
Until then, the app shows its packs and plans without buttons, and says "Payments are not enabled for this app yet."
Checkout
- The user presses Buy (a pack) or Subscribe (a plan) on the account page.
- The runtime creates a Stripe Checkout session. The price comes from the published manifest, never from the browser. The user's email is filled in.
- The payment is a destination charge to your connected account. WebRobot keeps its application fee: a share of the pack's price, or a percentage of each subscription invoice. The fee percentage is set by the platform;
billing.platformFeePctin the manifest is not used. - Stripe sends the user back to the app. The credits are added at once, and the account page says "Payment received — thank you!". If the payment is still being confirmed, it says "Payment being confirmed: the credits arrive shortly."
Payouts from your connected account to your bank follow your Stripe account's settings.
What Stripe tells the app
| Stripe event | Effect |
|---|---|
| Checkout completed | The session is read back from Stripe. A paid pack adds its credits; a plan is turned on for the user. |
| Invoice paid | The plan stays on, and the plan's credits are added for the period. |
| Subscription deleted | The plan is removed from the user. |
Crediting is idempotent: the return page and Stripe's notification can both arrive, and the credits are added once. A completed purchase is also an app event: triggers with on.payment fire (see Agents and automation).
Not available yet
- Users cannot cancel a subscription from the app.
- Payments are off on the preview address.
Limits
spec.limits holds the app's quotas. Each limit has an action, a max and a window.
action | What is counted | per honoured |
|---|---|---|
run | A user's form runs, all agents | user |
agent:<key> | A user's form runs of that agent (per absent or user); the starts of that agent by events (per: user or per: app, written explicitly) | user, app |
agents | Every agent started by events | app, user |
create:<collection> | Records a user creates, through forms and agent tools | user |
window | Meaning |
|---|---|
minute, hour, day | The last minute, hour, day |
month | The last 30 days |
total | Ever: a quota, such as "at most 3 projects in the free plan" (not for starts by events) |
All windows are sliding: they count back from now. rolling is accepted but has no effect.
limits:
- { action: "create:projects", max: 3, window: total, plans: { pro: 50, agency: -1 } }
- { action: run, max: 10, window: day, roles: [member] }
plansgives each plan or pack its own max;-1= unlimited; a user with several gets the highest. It applies to form runs and to records created by agent tools.rolesrestricts a form-run limit to those roles.- The app's admins are not limited on form runs and on records they create.
per: ipandper: org, and the actionschatandlogin, are accepted by the schema but not enforced throughspec.limits. Chat and sign-in have fixed limits: see Runtime.
When a limit is reached the user sees 429 with the reason, for example "limit reached: 10 per day", "limit reached: 3 in your plan", or for an agent tool "limit reached: 3 projects in the user's plan — the user can upgrade their plan". Starts by events are explained in Agents and automation.
What users see
The account view (type: account) shows:
- the balance;
- a Top up section: each pack with its price and credits and a Buy button; each plan with its price per month or year, its credits, a Subscribe button, and an active badge once subscribed;
- the user's connected keys, when the app has credentials;
- Movements: every line of the ledger, with date, reason and amount.
Give an app that sells packs or plans an account view: that is where the buttons are, and where Checkout sends the user back.
The run form shows an option gated by a plan the user does not hold as disabled, with "needs the plan …". The run page shows what was charged once the run is settled.
The admin view (type: admin) lists every user with their sign-up date, plans and balance, with a field to add credits by hand, and the latest runs.