Showing the advice
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.
Turn the advice into product cards: fetch the advised products, keep the order of the advice and leave out what the customer cannot buy. The examples continue with the label printer flow, first for a customer in a warehouse who prints up to 5,000 labels of 4 inch wide a day, then for a customer who labels boxes on a conveyor line.
The advice
The last step of the conversation returned this advice:
{
"data": {
"guidedSellingStep": {
"__typename": "GuidedSellingAdvice",
"headline": "Industrial label printers for up to 5,000 labels a day",
"items": [
{
"productId": 18243,
"reason": "Built for continuous labeling in a warehouse and prints up to 5,000 labels of 4 inch a day, which matches your volume.",
"clusterId": null,
"options": null,
"addOns": []
},
{
"productId": 18241,
"reason": "Also prints your 4-inch labels and leaves room to grow to 10,000 labels a day or 6-inch pallet labels.",
"clusterId": null,
"options": null,
"addOns": []
}
]
}
}
}
The advice holds a headline and up to three items with a reason each. The first item is the best fit. Both items here are products. An item with a clusterId is a configured cluster, see Showing a configured cluster, and addOns lists products to offer with an item, see Showing add-ons.
Fetching the advised products
Fetch the products by id, in the language of the conversation, with the fields your product cards need. Fetch every product the advice names in one query: the items, the products of their options and their add-ons.
query AdvisedProducts($productIds: [Int!]!, $language: String) {
products(input: { productIds: $productIds }) {
items {
... on Product {
productId
sku
names(language: $language) {
value
}
slugs(language: $language) {
value
}
price {
gross
net
}
inventory {
totalQuantity
}
}
}
}
}
Variables:
{
"productIds": [18243, 18241],
"language": "EN"
}
Expected response:
{
"data": {
"products": {
"items": [
{
"productId": 18241,
"sku": "LP-I640",
"names": [{ "value": "LP-I640 Industrial Label Printer" }],
"slugs": [{ "value": "lp-i640-industrial-label-printer" }],
"price": { "gross": 1895, "net": 2292.95 },
"inventory": { "totalQuantity": 6 }
},
{
"productId": 18243,
"sku": "LP-I440",
"names": [{ "value": "LP-I440 Industrial Label Printer" }],
"slugs": [{ "value": "lp-i440-industrial-label-printer" }],
"price": { "gross": 1195, "net": 1445.95 },
"inventory": { "totalQuantity": 24 }
}
]
}
}
}
Send the same API key and access token as for the rest of your storefront, so the customer sees their own prices. For more on fetching by id, see Fetch products by multiple IDs.
Keeping the order of the advice
The products query does not return products in the order of productIds. In the response above, the second advised product comes first. Put the products back in the order of the advice and attach each reason:
const byId = new Map(products.map((product) => [product.productId, product]));
const cards = advice.items
.filter((item) => byId.has(item.productId))
.map((item) => ({ product: byId.get(item.productId), reason: item.reason }));
Leaving out what the customer cannot buy
A flow advises without knowing who the customer is, so an advised product can be one that this customer may not see or buy, for example a product outside their orderlist or a hidden product. Show nothing of an advised product, its reason included, unless your own product query returns it for this customer. The reasons name the products, so a reason on its own already reveals the product.
A flow advises from the same selection for every customer. Your storefront knows what this customer may see and buy. The products query applies the same rules as your other product queries, so an advised product it does not return is one this customer cannot see: leave it out, as the filter above does.
The same goes for the other products in the advice:
- Leave out a configured cluster when its variant or the product of a required option is not returned. Leave out only that option when the product of an optional one is not returned.
- Leave out an add-on that is not returned.
By default products returns only products with status A (available). If your storefront also shows products with other statuses, for example products in presale, add them with statuses in the input.
When none of the advised items remains, do not show an empty list. Tell the customer that the advised products are not available for their account and offer a way to contact a sales rep.
Showing the products
- Show the headline above the products.
- Show each product as your regular product card, in the order of the advice, with its reason on the card. You can mark the first one as the best match.
- Take the name, image, price and stock from the product data. The reasons are the only text from the advice on the card.
- Render the headline and reasons as plain text.
Buying an advised product is your regular cart flow: start a cart with cartStart when there is none and add the product with cartAddItem. See Add a product to cart. Guided selling adds no cart operations of its own.
The React and Vue UI libraries have a compound ProductCard (ProductCard.Image, ProductCard.Name, ProductCard.Price and so on). Compose the card from its parts and place the reason between them. See UI components.
Showing a configured cluster
A flow can advise a cluster in a configuration: one of its variants with a product for each cluster option it fills. A customer who labels boxes on a conveyor line got this advice:
{
"data": {
"guidedSellingStep": {
"__typename": "GuidedSellingAdvice",
"headline": "A print and apply system for your conveyor line",
"items": [
{
"productId": 18302,
"reason": "Applies up to 20,000 labels a day from the right-hand side of your conveyor, and the air blow applicator handles boxes of different heights.",
"clusterId": 1830,
"options": [
{ "clusterOptionId": 1831, "productId": 18312, "quantity": 1, "isRequired": true },
{ "clusterOptionId": 1832, "productId": 18321, "quantity": 2, "isRequired": false }
],
"addOns": [
{
"productId": 18250,
"quantity": 1,
"reason": "Thermal transfer ribbons keep your labels readable through months of storage."
}
]
}
]
}
}
}
| Field | What it holds |
|---|---|
clusterId | The cluster |
productId | The chosen variant of the cluster: the product to show and add |
options | One entry for each cluster option the configuration fills: every required one and the optional ones the customer's answers call for |
options.productId | The chosen product of that cluster option |
options.quantity | How many of that product go with one configured cluster |
options.isRequired | true for a required cluster option. The customer cannot remove it from the configuration. |
Show the variant as the product card, with the option products listed on it as what is included, each with its quantity. Fetch them in the same products query as the variant. The customer may remove an optional one. For other changes, link to your regular page for the cluster.
Add the configuration to the cart in one call. childItems holds the option products, with their quantities for all units together, so multiply each quantity by the number of configured clusters the customer adds:
mutation AddConfiguredCluster {
cartAddItem(
id: "019abc12-3456-7def-8901-234567890abc"
input: {
productId: 18302
clusterId: 1830
quantity: 1
childItems: [
{ productId: 18312, quantity: 1 }
{ productId: 18321, quantity: 2 }
]
}
) {
items {
productId
quantity
childItems {
productId
quantity
}
}
}
}
For more on clusters in the cart, see Adding items with child items.
Showing add-ons
An item can come with add-ons: products the flow offers with it, such as consumables or accessories, each with a quantity and a reason. The cluster above comes with a box of thermal transfer ribbons. Whether a flow offers add-ons, and which, is up to the people who set it up.
- Show the add-ons under the item they belong to, each with its reason.
- Let the customer choose them. An add-on is a suggestion, not part of the advised product. A button that adds the item with its add-ons is fine.
- Add each add-on as its own cart line with
cartAddItem. Itsquantityis per one of the item, so multiply it by the number of items the customer adds. The cart merges the same product into one line by itself.
Showing advice without products
When nothing in the flow's selection meets what the customer needs, the advice has no items and the headline says so:
{
"data": {
"guidedSellingStep": {
"__typename": "GuidedSellingAdvice",
"headline": "None of our label printers takes labels wider than 6 inch",
"items": []
}
}
}
Show the headline with a way to contact a sales rep or specialist, and offer to start over.
Reporting what the customer does
Showing the advice needs no report: guided selling counts an advice it served as seen. When the customer converts an advised item, for example by adding it to the cart, requesting a quote or downloading its documents, report its productId with CONVERTED: for a configured cluster, that is the variant. See Reporting outcomes.