Commerce

Commerce is how a product earns: one Offer prices every Verb, a Meter counts each unit once, and people and agents pay inside the call. Every priced call gets a signed receipt, and the money lands in your Stripe account.

Capability families

Family	What it does
The catalog	The Offer is the one price source: a price per call, plans and seats, trials, free calls, credit packs, coupons, add-ons, committed use, quotes and invoices on terms
Entitlements and limits	What a Key may call, decided before the call runs: the plan's Entitlement, what it includes, the spend ceiling, and a rate limit that paying never lifts
Metering	Each priced unit counted once, by any unit the Offer names: a call, an answer row, 1,000 tokens, a minute, a seat, a read or an outcome
Payment by people	Stripe Checkout for credit packs and plans, subscriptions billed ahead, invoices on terms, tax on each charge, payment methods and tax details in the portal
Payment by agents	The 402 with a cure; `Max-Cost` on the call and ceilings on the Key; payment inside the call on the open agent-payment rails, drawn from a mandate
The agent-legible contract	Terms as data an agent accepts in the call, a signed receipt for every priced call, refunds by the published rule, and disputes opened with the receipt
Multi-party money	Several payees on one line; a charge on proof; client funds held until acceptance; a Marketplace's split and your share; holds and clawbacks
Payments for your Customers	Each Customer takes payments from its own customers on its own connected Stripe account, with your fee on each charge
Payouts and the sales record	Payouts to your Stripe account and to each supplier's; one record of every sale, refund, dispute, tax line and fee, with margin per Verb

Commerce adds its own Nouns to every product, the way Watch is a Noun on every API: Subscription, Balance, Invoice, Receipt, Refund, Dispute and Payout. Each has a lifecycle, writes its Events and answers on every Interface, so the portal and any console read the same state.

The sales record is the product's record of what it sold. Your company's books are not part of it: they read it through Events and the export.

Lifecycles and states

Thing	States	What moves it
A priced call	`quoted`, `reserved`, then `captured` or `released`	The gate reserves the price under the Limits before the run; a result captures it; a miss, a failure or a cancel releases it at 0
A `Balance`	`funded`, `low`, `empty`, then `funded` again	Each call draws once at its served price; Watches fire at 50, 80 and 100 percent; `empty` answers 402 with the packs
A `Subscription`	`trialing`, `active`, `past_due`, `cancelled`	Checkout starts it; renewal bills a month or a year ahead; a failed renewal retries on Stripe before it ends; a new plan price reaches it at renewal
An outcome charge	`held`, `charged`, `paid_out`, or `remedied`	The order holds the price; the move the Outcome contract names charges it; a rejection takes its remedy: `redo`, `refund` or `credit`
A `Refund`	`requested`, `granted` or `declined`, `paid`	The published rule grants it with no person; outside the rule it waits as Pending on the approver you name
A `Dispute`	`opened`, `answered`, `won` or `lost`	A Customer or its agent opens it with the receipt, and the call record and terms answer it; a card dispute arrives from Stripe as an Event
A `Payout`	`earned`, `pending`, `paid`, or `reversed`	Stripe pays your account and each supplier's on its schedule; a refund or a lost dispute reverses that line's shares

Every move above is a Verb and writes its past form: Subscription.renewed, Invoice.paid, Refund.granted, Dispute.opened, Payout.paid.

What you declare, what the platform does

You declare	The platform does
A price per Verb, by call, by consumption, by the month or by outcome	Meters each unit once and draws it from credits at the served price, or bills it on the plan
Plans, seats, trials, free calls and credit packs	Sells each through Stripe Checkout, runs every subscription on your Stripe account, and refuses past a plan with the next plan as the cure
The terms: the refund rule, the licence a sale grants, an Outcome contract	Renders them on the site and the offer card, records their acceptance in each call, and grants each refund the rule allows
The split, in a Marketplace or a Service API	Splits each payment per line on Stripe, holds a client's funds until acceptance, and claws back on a refund
Your fee on your Customers' own sales	Onboards each Customer's own connected account, and takes your fee on each charge
Your Stripe account, connected once	Calculates tax on each charge, signs every receipt, answers disputes with the evidence, pays out, and reconciles the sales record against Stripe

APIs.Dev's own share comes off each charge as a fee at your plan's published rate, and the sales record prints it line by line.

Example

The sample's Offer with terms: a price per answer, a Watch by the month, free calls, credit packs, and terms accepted in the call.

definition.ts · offer

15 lines

import { define } from 'apis.dev'

/** Any company by its domain, with its headcount and sector. */
export default define({
  name: 'companyfacts', domain: 'companyfacts.apis.dev',
  …
  // Company and its Source as before
  offer: {
    'Company.get': 0.002, 'Company.search': 0.005,      // per answer; a miss is free
    'Company.watch': { month: 0.1 },                    // per record, by the month
    free: { 'Company.get': 100 },                       // calls a month at 0
    credits: [10, 50, { pay: 200, get: 220 }],          // the packs Checkout sells
    terms: { refund: 'wrong-answer', license: 'internal-use' },  // accepted in the call
  },
})

Every priced reply carries X-Receipt-Id, and the receipt it names is signed by the seller.

companyfacts.apis.dev/receipts/rcpt_1

14 lines

{
  "id": "rcpt_1",
  "request": "req_3cd59a9a1ede10c5bf21",
  "seller": "companyfacts.apis.dev",
  "customer": "cus_Acme",
  "verb": "Company.get",
  "version": "v1",
  "price": 0.002,
  "currency": "USD",
  "paid": "credits",
  "terms": { "refund": "wrong-answer", "license": "internal-use" },
  "at": "2026-10-27T09:00:00Z",
  "signature": "ed25519:…"
}

The signature verifies against the keys at /.well-known/receipt-keys, so anyone checks a receipt with no account, and a dispute carries it as it stands.

Contracts with the other subsystems

Subsystem	What Commerce takes from it	What Commerce gives it
Definition and compile	The Offer, the terms and the split rules	A refusal at deploy for an unpriced Verb, a price below cost, or shares above the price; a higher price per call marked as breaking
Identity, access and policy	The mandate a caller presents	The price and the Entitlement, as inputs to the one decision
Model and records	The views it rebuilds	The sales record: revenue by Verb and Customer, margin, tax collected, refunds
Data and Sources	Each Source's `cost`, and the licence a sale may grant	Margin per Verb, and the licence terms printed on a per-read sale
Runtime	The gate's `price` step and the commit	A reservation before the run; the fact, its meter line and its receipt in one commit; every Stripe charge as a durable intent; Stripe's view reconciled as an observed Event
Work	Acceptance under an Outcome contract, a supplier's filled order	The charge on acceptance, each supplier's share released, a remedy paid as a refund or a credit
Interfaces and distribution	Every call, from every Interface	`X-Cost` on every reply, `offers` in a 402 or 403, Checkout on your Host, the offer card's price and terms, the receipt in MCP `_meta`
Trust and operations	Fraud, card-testing and chargeback signals; the Test twin	Money Events for every brake; a Test Key that never bills

The seam. Anything outside the product reads money through Events, webhooks and the export, and acts through the same Verbs. An invoice is product; the books it lands in are not.

What Customers and their agents meet

A person buying. The price page and its machine twin, Stripe Checkout for a pack or a plan, then a Live key. The portal holds the balance, the plan, invoices and receipts, payment methods, tax details, spend ceilings and cancellation.
A person paying on terms. A quote accepted as a Verb becomes an invoice on terms, paid on Stripe. The Entitlement starts on acceptance or on payment, as the Offer says.
An agent buying. It reads the offer card, asks quote for the exact price at no charge, and calls with Max-Cost. A 402 carries a cure it can pay within its mandate, and the call after payment goes through.
Anyone checking. Every priced call has a receipt that names the Version, the price and the terms, verifiable without the seller's help.
Anyone disputing. Dispute.open with the receipt; a refund the rule allows is paid with no person, and every other one waits on a named approver.
A supplier, in a Marketplace or a Service. Payout onboarding on Stripe, its share of each line it filled, and its tax forms.

An agent's purchase, in order:

It reads /.well-known/agents.json and the offer card: price per unit, terms, the refund rule and proof.
It asks quote for the exact price of its call, at price 0.
It calls with Max-Cost and its mandate.
Unpaid, it meets 402 with offers: Checkout links for a person, and a payment on the open agent-payment rails for itself.
It pays from its mandate and calls again with the same Idempotency-Key; the call runs once and is billed once.
It verifies the receipt's signature, and disputes with the receipt when the answer misses the terms.

One Offer is the only price: the reply, the page, the receipt and the bill read the same number.

Capability familiesCopy Anchor Link

Lifecycles and statesCopy Anchor Link

What you declare, what the platform doesCopy Anchor Link

ExampleCopy Anchor Link

Contracts with the other subsystemsCopy Anchor Link