BETA Product Intelligence API
The Hello Retail Product Intelligence API, which is in its Beta phase, employs cutting-edge artificial intelligence technology to offer an extensive analysis and insights about your product catalog. These valuable insights can significantly influence business decisions such as which products to retain in the inventory and when and how to distribute marketing resources. The Product Intelligence API goes beyond the traditional methods, using AI to extrapolate and understand potential trends and demand, thereby augmenting decision-making with data-driven insights.
The Graph API offers an analytical function that 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
This analytical operation utilizes a clustering technique, which aggregates similar products to the one submitted. Consequently, the results you receive will represent not just the single product you have submitted but a group of products bearing comparable characteristics. This method significantly boosts the data pool, enabling more accurate results.
Please be aware that while the model is based on a substantial dataset, it may not generate insights for every product you submit. This limitation is due to the varying data quantity and quality available for different products. In cases where sufficient data is lacking to deliver an accurate response to a product query, our system opts to send an empty response instead of potentially inaccurate data, thereby upholding the accuracy of the API.
We are continuously updating and improving the model.
Accessing and Authenticating GraphQL API
The data is made available in a GraphQL API that is available from the URL:
https://core.helloretail.com/pi/graphql
This page also has a GraphiQL test interface for running queries, and a "Docs" panel containing the full schema with all available fields.
To interact with the API, you will need to authenticate. Both methods require a Hello Retail account. If you don't yet have an account, you can create a new one on my.helloretail.com. There are two primary mechanisms for authentication:
-
User Session Authentication: If you are already logged into my.helloretail.com and try to access the API in your browser, you will be automatically authenticated. This method is primarily useful for testing.
-
API-key Authentication: For robust and efficient integration, especially when you need to integrate the API into your systems, it's recommended to use an API key. You can generate an API key from the 'API Keys' section on my.helloretail.com. Once you have the API key, you can supply it to the API by appending it as a query string parameter
apiKeyto the URL. The URL will then look something like this:https://core.helloretail.com/pi/graphql?apiKey=XXXXXXXXX
Usage
The GraphQL API exposes a single query, productInsight that accepts a product url, and it's associated website uuid from your Hello Retail configuration. Detailed documentation of the usage and the returned information can be found in the by visiting the graphql URL in a browser. You need to be logged in to my.helloretail.com to be able to access it, or alternatively provide the API key as mentioned above.
You can only request insights for products from websites that you have access to.
Before insights can be generated for a product, it must first be created in Hello Retail. Most often this happens through your product feed. Additionally, we require your product to have a description and a valid image before we will be able to match it to a group. There is also a delay when creating new products until this mapping has happened.
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.
Purchase next
For the purchase next API-endpoint you have to use our Unmanaged Recommendations API, using the BOUGHT_NEXT source type.
Below is an example in JavaScript:
async function loadRecoms() {
var data = {
websiteUuid: '{website id}',
trackingUserId: '{tracking user}',
requests:[{
trackingKey: 'testing',
count: 8,
sources: [
{
type: "BOUGHT_NEXT"
}
],
fields: ["title", "url",]
}]
};
var options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
}
const response = await fetch('https://core.helloretail.com/serve/recoms', options);
return await response.json();
}
loadRecoms().then((resp) => {
console.log(resp);
})