Choosing a price

Defining pricing covers how to express a price in a pay spec. This page covers the harder question: what number to put in price_usd, and why pricing for agent buyers works differently than pricing for humans reading a pricing page.

Agent summary

• Compute your cost floor per unit, then price on value delivered — not cost plus a reflex margin.
• Skip the free tier. Sandbox mode is your trial; per-request payments already remove signup friction.
• Your unit and scale are your comparison frame: agents rank endpoints by normalized cost, so choose the unit that matches what the caller values.
• Price variants by real cost and capability difference. Decoy tiers don't work on buyers that compute expected value.
• Keep prices legible at the human approval moment: spend caps and wallet prompts display your numbers verbatim.
• Measure revenue per caller and repeat-call rate, not raw call volume.

Start from your cost floor — then leave it

Every metered endpoint has a real serving cost: upstream API fees, inference tokens, compute, egress. Know that number per unit before anything else. If a request costs you $0.004 in upstream fees, that is your floor, not your price.

The common failure is pricing at cost plus a small reflex margin. A price increase is the highest-leverage change you can make: raising $0.01 to $0.013 is pure margin with zero acquisition cost, no extra infrastructure, and — for agent buyers — no pricing-page redesign. Most endpoints are underpriced because the developer anchored on their upstream bill instead of what the response is worth to the caller.

A useful test: if an agent calls your endpoint instead of doing the work itself, what did the caller save in tokens, time, or failed attempts? Price against that, not against your invoice.

You don't need a free tier

The classic argument for freemium is friction: signups die at the credit-card form, so you eat the cost of free users to keep the funnel open. Per-request payments remove that premise. An agent pays $0.01 as easily as it calls a free endpoint — there is no form, no card, no invoice to justify a free tier.

Free calls still cost you real money, and for inference endpoints every free request burns actual tokens. Instead of a free tier:

• Point integrators at sandbox mode. It is the trial: full 402 handshake, no real funds.
• If you want a taste of production, use a cheap first tier rather than a free one:

tiers:
  - up_to: 100
    price_usd: 0.001
  - price_usd: 0.01

A caller that won't pay a tenth of a cent to evaluate your endpoint was never going to convert. Charge well, and early.

Your unit is your comparison frame

Human buyers compare pricing pages; agents compare metering blocks. When an agent picks between providers in the catalog, it normalizes price_usd / scale and ranks by expected cost for its task. You can't decorate that comparison — but you choose its terms when you choose unit and scale.

Pick the unit that matches what the caller values, not just what your meter can count:

• A search API priced per requests is directly comparable and easy to budget. Good.
• A summarization API priced per input tokens punishes callers with long documents — the callers who value it most. Per requests or per output characters may frame you better.
• An inference endpoint should mirror the market's convention (per 1M tokens, split input/output) because agents estimate token counts before calling. A nonstandard unit here makes you harder to compare, and unpriceable calls lose to priceable ones.

The rule: be cheap in the unit your best callers actually consume, and be conventional where a convention already exists.

Variants are your tiers — price them honestly

Three-tier pricing pages lean on the decoy effect: a deliberately weak middle option that makes the target plan look good. That works on humans scanning a table. It does not work on an agent that computes cost against task requirements — a decoy variant is just a worse deal that never gets selected, and catalog noise that makes your listing harder to evaluate.

Price variants by genuine cost and capability difference, and say what the difference is in the endpoint description — variants themselves carry only param, value, and dimensions:

endpoints:
  - method: POST
    path: 'v1/generate'
    description: >-
      Text generation. model=fast is a small model (~1s) for classification
      and extraction; model=pro is a frontier model (~8s) for reasoning and
      long-form output.
    metering:
      variants:
        - param: model
          value: fast
          dimensions:
            - direction: usage
              unit: requests
              scale: 1
              tiers:
                - price_usd: 0.01
        - param: model
          value: pro
          dimensions:
            - direction: usage
              unit: requests
              scale: 1
              tiers:
                - price_usd: 0.10

The description is doing the work a pricing page used to do. An agent choosing fast vs pro needs to know why one costs 10x more; if the spec doesn't say, the cheaper variant wins by default.

The approval moment is still human

One surface in the flow is read by a person: the approval prompt. When a user sets spend caps or approves a session, your price appears exactly as you defined it. $0.01 per request is legible at a glance. $0.50 per 1,000,000 input tokens requires the user to estimate token counts before they can feel whether it's fair.

You don't need to abandon fine-grained units — but check what your pricing looks like at approval time:

• Prefer scale values that make the displayed price a number a human can reason about.
• If your natural unit is opaque (tokens, bytes), make sure the endpoint description translates it: "a typical request costs about $0.002."

A price a user can't evaluate in two seconds is a price they cap conservatively — or decline.

Measure segment quality, not volume

A lower price reliably buys more calls. That is not the goal. The metrics that matter for a metered endpoint:

• Revenue per caller, not calls per day. A thousand one-off probes at $0.001 are worth less than fifty integrations calling you daily at $0.01.
• Repeat-call rate. Agents that come back have embedded you in a workflow; agents that don't were comparison-shopping.
• Variant mix. If nobody selects your expensive variant, its value story isn't landing in the description — fix the copy before the price.

Volume tiers are the tool for rewarding the callers you want more of: keep the entry price honest and let discounts start where real integrations live.

tiers:
  - up_to: 10000
    price_usd: 0.01
  - price_usd: 0.006

Further reading

Several of these principles are adapted — and some deliberately inverted for agent buyers — from Revenue-Centric Design, a collection of SaaS pricing and conversion principles. The tactics that assume a human reading a pricing table don't survive contact with search_catalog; the core idea does: control how buyers compare, not just what you offer.