Core concepts
Pricing strategies
How you charge end users maps onto wallets, plans, markup, and job ceilings.
Seams meters every call in money. How you present that to end users is a product choice: pay as they go, prepaid packs, a monthly allotment, a price per finished job, or a mix. Use this map to pick the nouns, then follow the linked pages and examples for the wiring.
What you are choosing
| Question | What it decides |
|---|---|
| When money moves | Before use (prepaid), with use (metered), or with a finished job (outcome) |
| What they see | Dollars, named credits, seats, or “N replies / month” |
| Where margin lands | On each call (markup / sell price), at top-up, or in the plan price |
| What stops a runaway | Wallet empty, key / bundle spend cap, or an outcome ceiling on one job |
Strategies that work today
| Strategy | End user pays for | Seams nouns | Start here |
|---|---|---|---|
| Usage-based | What they actually called, at your price | Bundle markup or sell price · money wallet · optional key cap | Usage-based pricing |
| Prepaid credits | Balance bought up front | grants.issue (always micros) · markup at top-up | Prepaid credits |
| Plan + allotment | A subscription that mints allowance each period | bundles include · entitlement before wallet | Credit systems · Subscriptions |
| Outcome-based | A finished job (reply, summary, agent run) | outcomes ceiling · attribute outcome / outcome_id on calls | Outcome-based pricing |
| Resell with margin | Your rate on your provider credential | BYOK account · markup / sell price · margin reads | Reselling with markup |
| Per-seat / per-agent | A budget per agent or seat, not one shared pool | One end user + key + cap per agent | Per-seat agents |
You can combine them. A Pro plan can mint monthly credits, allow wallet top-ups when the pool runs out, and still put an outcome ceiling on each support ticket.
Usage-based
No pack vocabulary required. Allow models on a bundle, set markup or a fixed sell price per million tokens, mint a key, and let calls debit the money wallet. Empty wallet → insufficient_credit. Use a key or bundle spend cap so one loop cannot empty the account overnight.
Prepaid and plan credits
Prepaid top-ups always land on the money wallet in micros, convert UI “credits” at your edge if you sell packs that way. Recurring named credits attach to a bundle via bundles include and mint entitlement pools; one named currency per bundle, shareable across plans. See Credit systems.
Outcome-based
Sell a result, not a token count. Define an outcome with a spend ceiling for one run, pass the same outcome and outcome_id on every call that belongs to that job, and charge in your product when the run completes (or include N runs in a plan). Seams enforces the ceiling and attributes spend; your checkout still owns the invoice for “one reply.”
Where margin sits
| Place | When to use it |
|---|---|
| Bundle markup % | Fallback margin on provider cost when a model has no sell price |
| Sell price per model | You publish fixed $/MTok input and output on the bundle |
| At top-up | They buy $20 of balance; you keep a share once, calls run at cost-ish |
| In the plan price | Subscription revenue covers allotment; overage is separate if you allow it |
Ceilings are not prices
A balance is what they have. A spend cap is how fast one key or plan may spend. An outcome ceiling is how much one job may cost. None of those is the product price you show on a pricing page, they are the enforcement behind it.