Skip to main content

Reporting outcomes

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.

Report when your frontend shows the advice and when a customer adds an advised product to the cart. Guided selling counts these reports per conversation, which tells the people who manage the flow how often a conversation leads to a product in the cart. Both reports use the guidedSellingOutcomeReport mutation with the flow id and the conversationId of the conversation's steps.

The mutation​

mutation ReportGuidedSellingOutcome($input: GuidedSellingOutcomeInput!) {
  guidedSellingOutcomeReport(input: $input)
}

It needs the same access as the step: your frontend API key, with or without a logged-in user's access token.

Reporting that the advice was shown​

Send ADVICE_SHOWN once the advised products are on screen, after you left out what the customer cannot buy. List the products you actually show, in the order shown:

{
  "input": {
    "flowId": "01a10f3c-5b7e-7d42-9a61-3c8e2f4b7d90",
    "conversationId": "3f6c1a52-8e0b-4d7a-9c2e-5b8f0d4a7e19",
    "event": "ADVICE_SHOWN",
    "productIds": [18243, 18241]
  }
}

Expected response:

{
  "data": {
    "guidedSellingOutcomeReport": true
  }
}

Send it once, when the advice appears. Do not send it when the advice is empty or when no advised product is left to show.

Reporting an add to cart​

Send ADDED_TO_CART when the customer adds an advised product to the cart from the advice, with that product and the quantity added:

{
  "input": {
    "flowId": "01a10f3c-5b7e-7d42-9a61-3c8e2f4b7d90",
    "conversationId": "3f6c1a52-8e0b-4d7a-9c2e-5b8f0d4a7e19",
    "event": "ADDED_TO_CART",
    "productIds": [18243],
    "quantity": 2
  }
}

Expected response:

{
  "data": {
    "guidedSellingOutcomeReport": true
  }
}

Send one report for each add to cart, with one product. quantity defaults to 1. When the product was already in the cart, report the number added, not the new total.

Sending reports without holding up your storefront​

A report must never slow down or break the storefront:

  • Do not wait for the response, and never show a failed report to the customer.
  • Send the report from your server, like the step, with a fixed mutation and the flow id from your configuration. The browser sends only the conversation id, the event, the product ids and the quantity.
  • In the browser, post to your route with keepalive, so the report still goes out when the customer moves on to the cart or checkout:
type OutcomeReport = {
  conversationId: string;
  event: 'ADVICE_SHOWN' | 'ADDED_TO_CART';
  productIds: number[];
  quantity?: number;
};

export function reportOutcome(report: OutcomeReport): void {
  fetch('/api/guided-selling/outcome', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(report),
    keepalive: true,
  }).catch(() => {});
}

/api/guided-selling/outcome stands for the route on your server that sends the mutation.

How reports are counted​

The flow's statistics count conversations: how many showed the advice and how many had an advised product added to the cart. A repeated ADVICE_SHOWN report changes nothing. The number of products added to carts adds up the quantities of every ADDED_TO_CART report, so send that report once for each add to cart.

A report carries no customer data. The conversationId ties it to the steps of the conversation. A report for a conversation that guided selling has no steps for is not counted.

Limits and errors​

FieldLimit
productIds1 to 20 products
quantity1 or more. Only for ADDED_TO_CART.

A report that breaks a rule returns GUIDED_SELLING_INPUT_INVALID_ERROR with each problem in extensions.problems:

{
  "errors": [
    {
      "message": "The input is invalid: quantity must not be less than 1",
      "path": ["guidedSellingOutcomeReport"],
      "extensions": {
        "code": "GUIDED_SELLING_INPUT_INVALID_ERROR",
        "problems": ["quantity must not be less than 1"]
      }
    }
  ],
  "data": null
}

An unknown flow id returns GUIDED_SELLING_FLOW_NOT_FOUND_ERROR. Both point to a problem in your integration, so log them.

See also​