Commerce flows

Commerce flows are a separate state machine from project shopping guides. Definitions are Studio-ready YAML/JSON documents (compiled techmaps plus custom fixtures). Sessions keep a ledger and step cursor. Every route requires search:read.

Flows stay off until the index sets settings.flows.enabled (console Flows Studio under /flows, or the matching oRPC settings). Listing and reading definitions work with the flag off; creating or advancing a session returns 403 FLOW_DISABLED when the flag is false.

List or fetch a definition:

GET /api/v1/indexes/{slug}/flows
GET /api/v1/indexes/{slug}/flows/{flowId}

Start a session (flow_id, optional client_id, or free-text text for trigger matching / default flow):

POST /api/v1/indexes/{slug}/flows/sessions
{"client_id":"visitor-42","flow_id":"commerce.simple-product-pick"}

Advance with optimistic concurrency. Send the last data.revision as expected_revision:

POST /api/v1/indexes/{slug}/flows/sessions/{sessionId}/advance
{"expected_revision":1,"answer":{"value":"acme"}}

A search step may attach retrieval proof (hits from the same searchForIndex path as other APIs). catalog_match and quote reuse the shopping-guide product helpers when nested guide state is present: pendingActions upgrade to resolved or incomplete, and the response may include catalog / quote. If bindings or stage are not ready, status stays needs_guide_session with an endpoint hint for POST .../guide/sessions/{id}/recommendations or .../quotes (see project shopping guides). Custom flows without guide state get unsupported — never a silent no-op.

The assistant stream starts a commerce flow when flows are enabled and a trigger matches (preferred over defaultFlowId). Techmap flows may start the same seeded session as Studio. Pass the prior flow session id as conversation_id to resume; say cancel/отмена or clarify/уточните to send a structured command instead of a slot answer. Catalog/quote and ask options surface as SSE ui blocks (product_cards / guide_actions).

A stale revision returns 409 FLOW_REVISION_CONFLICT. Unknown flow or session: 404 FLOW_NOT_FOUND. Incomplete answers: 422 FLOW_INCOMPLETE.

Full request and response shapes live in the generated OpenAPI reference for these operations (listFlowDefinitions, getFlowDefinition, createFlowSession, getFlowSession, advanceFlowSession).