Reporting outcomes
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 a customer converts an advised product: adds it to the cart, requests a quote for it, downloads its documents or does anything else your storefront counts as a conversion. Guided selling counts these reports per conversation, which tells the people who manage the flow how often a conversation leads to purchase intent. The report uses the guidedSellingOutcomeReport mutation with the conversationId of the conversation's steps, and counts for the flow the conversation started on.
Showing the advice needs no report: guided selling counts an advice it served as seen.
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 a conversion
Send CONVERTED when the customer converts an advised product from the advice: adds it to the cart, puts it on a quote request, downloads its documents or does anything else your storefront counts as a conversion. Send that one product, and the quantity when there is one. For a configured cluster, send its variant: the productId of the item. Add-ons and the products of a cluster's options are not reported.
{
"input": {
"conversationId": "3f6c1a52-8e0b-4d7a-9c2e-5b8f0d4a7e19",
"event": "CONVERTED",
"productId": 18243,
"quantity": 2
}
}
Expected response:
{
"data": {
"guidedSellingOutcomeReport": true
}
}
Send one product per report. quantity is kept with the conversation for reference and defaults to 1, so leave it out when the conversion has no quantity, such as a download. It does not change the statistics: each advised product counts once per conversation.
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. The browser sends only the conversation id, the event, the product id 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: 'CONVERTED';
productId: 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 the conversations that reached the advice and how many of them converted an advised product. Each advised product counts once per conversation, however often it is reported and in whatever quantity. So report every conversion as it happens: a repeated report changes no number.
Only advised products count. A report for another product, an add-on included, or for a conversation that never reached the advice returns true and is kept with the conversation, but counts in no figure.
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 ignored, and so is any report after the 50th of a conversation. The mutation then returns false.
Limits and errors
| Field | Limit |
|---|---|
productId | The advised product, for a configured cluster its variant. 1 or higher. |
conversationId | 1 to 128 characters, the same as in the steps |
quantity | 1 to 1,000, 1 when left out |
| Reports per request | 1 |
| Reports per conversation | 50. Later ones are ignored. |
A report that breaks a rule returns BAD_REQUEST, the same as everywhere in the GraphQL API, with each broken rule in extensions.originalError.message:
{
"errors": [
{
"message": "Bad Request Exception",
"path": ["guidedSellingOutcomeReport"],
"extensions": {
"code": "BAD_REQUEST",
"originalError": {
"message": ["quantity must not be less than 1"],
"error": "Bad Request",
"statusCode": 400
}
}
}
],
"data": null
}
It points to a problem in your integration, so log it.