OpenKarta
← All posts
Spec 2026-04-20 7 min read

Why eight verbs is enough.

Every commerce-API standardization effort that came before us added too much surface. Here is the thinking behind keeping it down to discover, search, get, quote, checkout, status, cancel, return.

Surface area is liability

Every verb the wire format introduces is a contract every conformant agent must satisfy and every consumer agent must understand. Three additional verbs sound cheap until you multiply them by five item types and a daily conformance sweep. The protocol has to be small enough that a competent backend engineer can read the spec end-to-end before lunch.

The eight, justified

discover declares the agent. search and get answer "what do you have." quote freezes a price. checkout binds the buyer. status reports state. cancel reverses commitment before fulfillment. return reverses commitment after delivery. There is no eighth concern that recurs across every commerce category.

What we left out

No subscriptions, no installments, no auctions, no negotiation, no promotions, no loyalty. Each of these is real, important, and a separate spec. Folding any one of them into the core verbs would have doubled the surface for the 90% of merchants who do not need them.

Extensibility, the boring way

Item-type-specific blocks (productCapabilities, stayCapabilities, etc.) are the extension point. A new item type adds one block and zero verbs. A new behavior on an existing type adds an enum value and zero verbs. The verb set is meant to be stable for years.

More from the protocol.