Skip to main content

Showing the advice

Not yet available

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, for a customer in a warehouse who prints up to 5,000 labels of 4 inch wide a day.

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."
        },
        {
          "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."
        }
      ]
    }
  }
}

The advice holds a headline and up to three products with a reason each. The first item is the best fit.

Fetching the advised products​

Fetch the products by id, in the language of the conversation, with the fields your product cards need:

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 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.

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 products 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 reason is 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.

Using the Storefront SDK?

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 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​

Once the products are on screen, report it with ADVICE_SHOWN, and report each add to cart of an advised product with ADDED_TO_CART. See Reporting outcomes.

See also​