---
title: "Commerce"
url: /commerce
---

# Commerce

> One Offer prices every Verb; people and agents pay inside the call, every priced call answers a signed receipt, and money splits and pays out on Stripe.

Commerce is how a product earns: one [Offer](/reference/platform.md#offer) prices every Verb, a [Meter](/reference/platform.md#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](/reference/platform.md#entitlement) and limits | What a [Key](/reference/platform.md#key) may call, decided before the call runs: the plan's [Entitlement](/reference/platform.md#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](/every-product.md), 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](/reference/platform.md#limit) 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](/reference/platform.md#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](/reference/platform.md#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](/patterns.md#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.

```ts title="definition.ts · offer"
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.

```json title="companyfacts.apis.dev/receipts/rcpt_1"
{
  "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](/patterns/dataset-api.md#how-a-field-is-filled)'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](/reference/platform.md#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](/reference/platform.md#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](/reference/platform.md#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:

1. It reads `/.well-known/agents.json` and the offer card: price per unit, terms, the refund rule and proof.
2. It asks `quote` for the exact price of its call, at price 0.
3. It calls with `Max-Cost` and its mandate.
4. Unpaid, it meets 402 with `offers`: Checkout links for a person, and a payment on the open agent-payment rails for itself.
5. It pays from its mandate and calls again with the same `Idempotency-Key`; the call runs once and is billed once.
6. 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.