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. An advised product can be a cluster in a configuration, and it can come with add-ons: other products to offer with it. 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 and clusters 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 mutation. 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 Editor or Owner 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 can finish on it for a day. |
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 and clusters the flow may advise or offer as add-ons, each with a short description and the attributes that tell them apart. A cluster holds its variants and its cluster options. 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 customer converted an advised product, for example by adding it to the cart, requesting a quote or downloading its documents.
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 and clusters from its catalog, at most three items, best first, each with a one-sentence reason based on the customer's answers
- configures an advised cluster with one of its variants and a product for every required cluster option, and fills an optional cluster option only when the customer's answers call for it
- offers add-ons only where your instruction says to, only products from the catalog and never the advised product itself or one of its option products
- never states a price. When cost comes up, it says that prices are not part of the advice, unless the flow's instruction says what to tell the customer.
- 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 it:
- the number of options and items
- every advised product, cluster, option product and add-on is in the catalog
- a cluster's variant and option products belong to that cluster, with one product per cluster option
- every required cluster option is filled. One the model left out is filled with its default product when it has one.
- quantities are within their range
A step that fails the check is generated again once, within the same 45 seconds. 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.
When you create a flow, replace its key or publish a version, guided selling first asks Anthropic whether it accepts the key and knows the version's model. That check generates nothing, so it costs nothing. A refused key or an unknown model stops the change with Anthropic's reason. When Anthropic cannot answer right then, the change goes ahead.
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. It does not do this after a typed answer, because other customers rarely type the same answer.
- 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 that follows a typed answer is stored for 15 minutes and reused for anyone who gives exactly the same answers in that time. After that, it is written again.
- The model vendor caches the instruction and catalog, so they are billed at a fraction of the normal rate while model calls follow each other within about five minutes. After a quiet spell, the next call stores them again, at a little more than the normal rate.
The model calls behind every step, with their token counts, are part of the conversation history. See Conversations and conversion.
The budget of model calls
Each environment (tenant) has a budget of model calls, shared by all its flows:
| Budget | Model calls |
|---|---|
| Steps a customer waits for | 60 per clock minute |
| Preparing steps in advance | 30 per clock minute, on top of the 60, so preparing never uses the customers' calls |
| All model calls together | 10,000 in the last 24 hours |
Every call counts, a retry and a call that fails included. So a flow with a refused key or a model Anthropic does not know uses up the budget of every flow in the environment while customers keep trying it.
When a budget is used up, steps that need a model call fail with GUIDED_SELLING_QUOTA_EXCEEDED_ERROR until it frees up. extensions.reason says which budget: MINUTE or DAY. extensions.retryAfterMs says when it frees up, which for the daily cap can be most of a day. The opening question and stored steps keep working. Preparing steps in advance waits for the budget instead of failing, and pauses first when Anthropic asks to slow down.
Access
| Operations | Who can run them |
|---|---|
guidedSellingStep, guidedSellingOutcomeReport | Any API key, including a frontend key without roles, with or without a logged-in user's access token |
guidedSellingFlows, guidedSellingFlow, guidedSellingFlowVersions, guidedSellingFlowStats | Configuration role, Viewer, Editor or Owner |
guidedSellingFlowVersionCreate, renaming a flow with guidedSellingFlowUpdate and testing a draft | Configuration role, Editor or Owner |
guidedSellingFlowCreate, guidedSellingFlowVersionPublish, guidedSellingFlowDelete, switching a flow on or off and replacing its key with guidedSellingFlowUpdate, guidedSellingConversations, guidedSellingConversation, guidedSellingConversationDelete | Configuration role, Owner |
Recorded conversations can contain what customers typed, so reading them needs Owner access. Switching a flow on or off, replacing its key and publishing change what customers get, so they need Owner access too. 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.