Understanding 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 leads a customer to the right product with a few questions, the way an experienced sales rep would. The customer answers each question by picking an option or by typing in their own words. After a few steps they get advice: up to three products, each with a one-sentence reason why it fits.
The questions and the advice come from a guided selling flow: selling knowledge and a selection of products that a merchant or partner sets up and publishes. Your frontend runs the conversation and shows the advised products as its own product cards, with the customer's prices, stock and add to cart. This page explains the model. The practical pages show how to run a conversation, show the advice and report what customers do with it.
One query per step
A conversation is a series of calls to one query, guidedSellingStep. Each call returns one of two types:
| Result | What it holds |
|---|---|
GuidedSellingQuestion | The next question with two to six options, a short acknowledgement of the previous answer and whether the customer may type an answer instead |
GuidedSellingAdvice | A headline and up to three advised products, best first, each with a reason |
The first call returns the opening question. It is written in advance by whoever set up the flow, so it comes back instantly. Every later question is chosen by the flow's AI model from what the customer said so far. The model stops asking as soon as the answers identify the right products, and at the latest when the flow's question budget is spent.
Your frontend keeps the conversation
Guided selling keeps no session for the customer. Your frontend keeps the conversation as an ordered list of answers and sends the whole list on every call. Each answer refers to the question it answers:
| The customer | The answer you add |
|---|---|
| Picks an option | { "questionId": "...", "optionId": "..." } |
| Types an answer | { "questionId": "...", "text": "..." } |
Because every call carries the whole conversation, no call depends on an earlier one. This makes the rest simple:
- Retrying a call is safe.
- Going back is sending the list without its last answer.
- Starting over is sending an empty list with a new conversation id.
- There is nothing to create before a conversation and nothing to clean up after it.
The conversationId is an id you generate for each conversation, for example a UUID. It groups the steps of one conversation in the flow's history and ties your outcome reports to them. It has no meaning to guided selling and must not contain personal data.
Versions are handled for you
A flow changes through versions. Every question id carries the version that produced it, so a conversation that is running when a new version is published finishes on the version it started on. New conversations start on the new version.
You do not send a version. The version field of the input lets the people who manage a flow test a version before it is published, and a storefront key cannot use it.
The advice holds ids and reasons
The advice names products by productId and gives a reason for each. It contains no names, prices, stock or images. You fetch those with the product queries you already use, so the customer sees their own prices and assortment, and you show the advised products as your regular product cards. Leave out products the customer cannot buy, for example products that are not on their orderlist.
The order of the items is the ranking: the best fit comes first.
The advice can be empty. That happens when nothing in the flow's selection meets what the customer needs, and the headline then says so. Offer a way to contact a sales rep or specialist in that case.
The flow never mentions prices. Whether a product card shows a price is up to your frontend, as for any other product.
Response times
| Step | Typical response time |
|---|---|
| The opening question | Milliseconds. It is written in advance. |
| A step reached by picking options | Usually milliseconds. While the customer reads a question, guided selling prepares the step each option leads to. |
| A step after a typed answer or on a path no customer took before | 5 to 20 seconds. The AI model writes the step for this customer. |
Design for both speeds: keep the current question on screen while the next step loads and explain the wait when it takes longer. A step gives up after 45 seconds and returns an error. Running a conversation has the details.
What you need
| You need | Where it comes from |
|---|---|
| The flow id | Whoever set up the flow. It is configuration for your frontend, like a channel id. |
| An API key | The frontend API key you already use. The step needs no role, the same as reading the storefront catalog. It also works with a logged-in user's access token. |
| The language | The language of your storefront, in Propeller format such as EN or NL. It must be one of the flow's languages. |
You do not fetch anything before the first question. One query runs the whole conversation.
Measuring results
When your frontend shows the advice and when a customer adds an advised product to the cart, you report it with the guidedSellingOutcomeReport mutation. The flow's statistics then show how many conversations reached the advice and how many led to a product in the cart. See Reporting outcomes.
How this relates to products and the cart
Guided selling decides what to ask and what to advise. Everything about the products stays with your frontend: you show the advice with the queries from Querying products, and buying an advised product is the regular flow from Cart management. Setting up and publishing flows is covered in Guided selling in the Platform section.