Commerce

Two more verbs

quote

Takes what you want, returns a Cart priced by the seller.

buy

Takes a cart that is ready, runs the decision, settles, returns an Order.

Both run across the prescriptive checkout standard and the capability-based one behind a single machine: discover, quote, authorise, settle. The vendor shapes stay inside their adapters. What you handle is a neutral Cart and Order.

Where a cart can be

priced

The seller has priced it. Not yet buyable.

escalation_required

Something needs a person on the seller's side. Deliberately not the same as priced: it demands the opposite next move, and the only way forward is the continue link.

ready

Buyable. Authorising anything else throws.

authorized

The payment passed the gate.

completed

The seller fulfilled it.

canceled

It ended.

The price is the seller's, not the caller's

The payment is built from the cart total the seller returned, never from an amount the caller passed in. That is the reason commerce is its own tier rather than a catalogue lookup followed by pay: an agent that could name its own price is an agent that can be talked into naming the wrong one.

The idempotency key is derived from the protocol and the cart id, so retrying a checkout cannot become a second order.

What we do not become

Commerce holds no means to settle. Authorising goes through the same injected payment path as everything else, and the seller remains the merchant of record. We are not in the middle of the sale; we are the decision between the price and the payment.

That holds over HTTP as well. The engine the server is handed is the tier built over the deployment's own gated payment: it carries no settler, no rail and no kernel. So the two routes reach a rail by exactly one path, the one /pay takes, and the tier cannot move money by itself.

Over HTTP

/quote prices a cart and commits nothing. /buy drives the checkout to ready and authorises through the same gate, audit and settle path as /pay, and it is under the same fail-closed rule for the same reason.

/buy takes an idempotencyKey of its own and it is namespaced separately from the payment one. The two routes share a store, and a key a caller used on /buy and a key a caller used on /pay are different things, so reusing one across both cannot collide. A prior settled outcome is replayed rather than bought again. An upstream failure that could succeed on a retry is not stored, so the same key can be sent again.

A cart that is not ready is refused rather than authorised, and the refusal carries the status the cart stopped in along with the continue link, so the way forward is in the response instead of a bare error. A seller refusal that the checkout standard itself classed as needing a person is reported as a denial, not as a retryable fault.

Declared against negotiated

A seller publishes what it is capable of. What matters is not that list but the intersection the seller actually selected for this exchange. Declared is a precondition; negotiated is the thing to gate on, and they are kept apart for that reason.

Afterwards

Order events flow back in as evidence rather than as fact. An unauthenticated assertion never becomes an observed fulfilment at all, and a successful read with nothing observed is an ordinary outcome rather than a failure. What survives that filter is graded on the same evidence ladder as everything else.