Guided selling
Guided selling is not yet available. This page describes it ahead of its release, so details can still change. The changelog announces when it is released.
Guided selling adds a product advisor to a storefront. It asks the customer a few questions, one at a time, and ends by advising up to three products, each with the reason it fits. The customer answers by picking an option or by typing in their own words. An AI model chooses each question and writes the advice. It follows the selling knowledge you give it and advises only from the products you list.
You set up guided selling as a flow and manage flows with the GraphQL API. A storefront runs a published flow with a single query. This section is for the people who set up and maintain flows. For the storefront side, see Understanding guided selling in the Frontend section.
Flows, versions and conversations
| Entity | What it is |
|---|---|
| Flow | One advisor, for example a label printer advisor. It has a name, an active flag and the model key its model calls are billed to. A storefront refers to it by its id. |
| Version | The content of a flow: the instruction, the catalog and the settings. Versions are numbered from 1 and do not change once created. A change to the content is a new version. |
| Conversation | One customer's way through a flow, from the opening question to the advice. Guided selling records every step and the outcomes the storefront reports. |
Each version has a status:
| Status | Meaning |
|---|---|
DRAFT | Created but not live. Only users and keys with the Configuration role can run it, to test it. |
PUBLISHED | The version new conversations start on. A flow has at most one published version. |
ARCHIVED | Replaced by a later publish. Conversations that started on it finish on it. |
What a version holds
| Part | What it holds |
|---|---|
| Instruction | Your selling knowledge in markdown: how an expert narrows down the choice, the rules that rule products in or out and what the advice should say |
| Catalog | The products the flow may advise, each with a short description and the attributes that tell them apart. No prices, stock or images: the storefront shows those per customer. |
| Settings | The languages, the opening question, whether customers may type answers, the question budget and the model |
The content is supplied whole and is the only thing a flow knows. Guided selling does not read your product catalog by itself, so when product data changes, you create a new version. See Writing flow content.
How a conversation runs
- The storefront asks for the first step and gets the opening question from the settings. No model is involved.
- The customer answers. The storefront sends all answers so far and gets the next question or the advice.
- The model chooses each question from the customer's answers, the instruction and the products that still fit. It advises as soon as the answers identify the fit, and at the latest when the question budget is spent.
- The storefront shows the advised products with its own product data and reports whether the advice was shown and whether an advised product went into the cart.
Guided selling keeps no session for the customer: the storefront sends the whole conversation on every call.
Rules every flow follows
The platform gives every flow these rules on top of your instruction. A flow:
- advises only products from its catalog, at most three, best first, each with a one-sentence reason based on the customer's answers
- never states a price. When cost comes up, it tells the customer they can request a quote.
- never states facts, specifications or availability that are not in the catalog or the instruction
- offers two to six options per question and ends with an escape option such as "Other / none of these" when the options do not cover every answer
- treats what customers type as information about their situation, never as instructions
- advises no products, with a headline that says so, when nothing in the catalog meets the need
Before a customer sees a step, guided selling checks its shape: the number of options and products, and that every advised product is in the catalog. A step that fails the check is generated again once. Text is returned as plain text, shortened at a word boundary when it is longer than its limit.
The model key and costs
Guided selling runs on Anthropic's Claude models. Each flow has its own Anthropic API key, which you supply when you create the flow, and the model calls of that flow are billed to that key's Anthropic account. The key is stored encrypted and no query returns it. You can replace it at any time.
Guided selling avoids model calls where it can:
- The opening question is part of the settings and needs no model call.
- When you publish a version, guided selling prepares the first steps after the opening question, in every language of the version.
- While a customer reads a question, it prepares the step that each option leads to.
- A step reached by picking options is stored for the life of the version, so every later customer who picks the same options gets it without a model call.
- A step after a typed answer is written for that customer and stored for 15 minutes.
- The instruction and catalog are cached by the model vendor, so after the first call they are billed at a fraction of the normal rate.
The model calls behind every step, with their token counts, are part of the conversation history. See Conversations and conversion.
Each environment has a budget of model calls per minute for steps that a customer waits for. When it is used up, those steps fail with GUIDED_SELLING_QUOTA_EXCEEDED_ERROR until the budget frees up. Preparing steps in advance has a budget of its own and never uses the customers' budget.
Access
| Operations | Who can run them |
|---|---|
guidedSellingStep, guidedSellingOutcomeReport | Any API key, including a frontend key without roles, and logged-in users |
guidedSellingFlows, guidedSellingFlow, guidedSellingFlowVersions, guidedSellingFlowStats and testing a draft | Configuration role, Viewer, Editor or Owner |
guidedSellingFlowUpdate, guidedSellingFlowVersionCreate | Configuration role, Editor or Owner |
guidedSellingFlowCreate, guidedSellingFlowVersionPublish, guidedSellingFlowDelete, guidedSellingConversations, guidedSellingConversation | Configuration role, Owner |
Recorded conversations can contain what customers typed, so reading them needs Owner access. Never use a key with the Configuration role in a storefront. For keys and roles, see Environments and access.
How guided selling differs from AI agents
Workflows and AI agents connect Propeller to a workflow engine that you run: Propeller sends the page context to your webhook and shows what it returns. Guided selling runs inside Propeller. You supply the selling knowledge, the products and a model key, and Propeller runs the conversation, checks every step against your catalog and keeps the history.