Insights for a Single Product¶
The productInsight query accepts a specific product (identified by its url) and returns comprehensive data insights about:
- Product Lifetime Value
- Recurring nature of the product and its timeline
- Typical discount percentages at which the product is sold
- The typical time of day when the product is purchased
- Retention rate of customers, who bought this product
- Quarterly sales, when do people tend to buy the product throughout the year
The API is available on the Product Intelligence API URL, with the same authentication as the rest of the API:
https://core.helloretail.com/pi/graphql
Usage¶
The query accepts a product url and its associated website uuid from your Hello Retail configuration. You can only request insights for products from websites that you have access to.
Because data quantity and quality vary between products, some products will return an empty response instead of insights.
To fetch information about a specific product you could send a GraphQL query like the following.
query {
productInsight(
url: "https://example.com/products/baggy-denim-jeans-5",
website: "a7ce8931-6473-4627-9127-ceafa74ae0a8") {
productLifetimeValue
retentionRate
isRecurrent
overallRecurrence
recurringPeriodWeekly {
start
end
}
returnsPeriodWeekly {
start
end
}
recurrenceDataWeekly {
week
probability
}
discountData {
percentageRangeFrom
percentageRangeTo
probability
}
}
}
Tip: Try copying the above query to the graphql tester, modify the product information to be one of your own products, and execute the query.
This will return a result like the following. The found information is
productLifetimeValue: The expected further income that can be expected from customers buying this product.retentionRate: The percentages of customers that bought the current product which came back to buy something else.isRecurrent: Our assessment of whether this product is generally something that customers buy more than once.overallRecurrence: The percentages of customers who buy this product (or a similar one) again in the future.recurringPeriodWeekly: Some products will show a strong recurring pattern, where most customers will re-purchase the same product after a fixed period. For products with such a peak, this data point will contain the first and last week of this peak period.returnsPeriodWeekly: Some products show strong recurrence in the first few weeks. In some cases, we determine that this is not true recurrence, but rather customers that have returned a product, and reordered a similar one (such as a different size). For products with this behaviour, this data point contains the first and last week of this peak period.recurrenceDataWeekly: List of data points describing the probability of a repurchase happening a certain number of weeks after the initial purchase, if a repurchase happens at all. This data is the basis for the recurring- and returns periods.discountData: List of data points describing the probability of a purchase happening when the product has a certain discount. The data is split into ranges of discount percentages. The range where bothpercentageRangeFromandpercentageRangeTois 0, contains the cases where the product was sold at the original price.
{
"data": {
"productInsight": {
"productLifetimeValue": 33,
"retentionRate": 0.591460449961798,
"isRecurrent": true,
"overallRecurrence": 0.14423277282801558,
"recurringPeriodWeekly": null,
"returnsPeriodWeekly": {
"start": 1,
"end": 1
},
"recurrenceDataWeekly": [
{
"week": 1,
"probability": 0.22848261973557482
},
{
"week": 2,
"probability": 0.11544523246650906
},
{
"week": 3,
"probability": 0.062253743104806934
},
{
"week": 4,
"probability": 0.046361964801681116
},
{
"week": 5,
"probability": 0.03918220821294107
},
[...]
{
"week": 52,
"probability": 0.005165922423605639
}
],
"discountData": [
{
"percentageRangeFrom": 0,
"percentageRangeTo": 0,
"probability": 0.5775372705516862
},
{
"percentageRangeFrom": 1,
"percentageRangeTo": 10,
"probability": 0.010033529289191698
},
{
"percentageRangeFrom": 11,
"percentageRangeTo": 20,
"probability": 0.06457071775410592
},
{
"percentageRangeFrom": 21,
"percentageRangeTo": 30,
"probability": 0.1168157909691922
},
[...]
{
"percentageRangeFrom": 91,
"percentageRangeTo": 100,
"probability": 0.0012186728463272484
}
]
}
}
}
Example request using javascript¶
The example query from above can also be sent using the JavaScript fetch API:
const query = `query {
productInsight(
url: "https://example.com/products/baggy-denim-jeans-5",
website: "{website id}") {
productLifetimeValue
retentionRate
isRecurrent
overallRecurrence
recurringPeriodWeekly {
start
end
}
returnsPeriodWeekly {
start
end
}
recurrenceDataWeekly {
week
probability
}
}
}`;
const response = await fetch("https://core.helloretail.com/pi/graphql?apiKey=XXX", {
"headers": {
"Content-Type": "application/json"
},
"body": JSON.stringify({query}),
"method": "POST"
});
console.log(await response.json());
Considering the data retrieval process from the API might be slower than desired, we advise implementing periodic querying of the products and storing it in a local database. This strategy ensures quick and efficient data access, improving overall performance.