Get the engagement report
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/reports/engagementCosts 1 rate-limit point · Rate limits
Back-in-stock "Notify me" button engagement: impressions, clicks, click rate, signups and signup rate, shop-wide and per variant: the merchant's Products > Engagement view.
Rates use unique shoppers; total_* fields count every event. from/to default to the shop's lifetime. variants is paged and sorted by sort_by (default impressions); shopify_variant_ids narrows it. This is button engagement, not conversion: orders from notified customers are in /back_in_stock/reports/summary. pixel_active is false until the STOQ web pixel is set up (POST /account/web_pixel/enable); the dashboard shows a set-up prompt instead of these numbers then. Each variant row's image_url is the variant's stored image, else the product's (null if none is stored).
Also searched asnotify me engagementback in stock funnelclick ratesignup rateback in stock button engagement
Query parameters
fromstringFirst day of the window. Default the day the shop installed the app.
tostringLast day of the window. Default today.
shopify_market_idstringOnly engagement in this Shopify market, as a gid or a numeric id.
shopify_variant_idsarrayOnly these Shopify variants, as gids or numeric ids (a comma-separated string also works), up to 250.
sort_bystringColumn to sort variants by. Default impressions.
One ofimpressionsclicksclick_ratesignupssignup_ratetotal_impressionstotal_clickstotal_signupsDefault"impressions"directionstringSort direction. Default desc.
One ofascdescDefault"desc"pageintegerPage of results to return, starting at 1.
Default1per_pageintegerVariants per page, 1 to 250. Default 50, or 250 when shopify_variant_ids is given.
Returns
pixel_activebooleanExample:truewindowobjectThe date range the figures cover. Null when range is all_time.
Show 2 child attributesHide child attributes
fromstringStart of the range, ISO 8601.
tostringEnd of the range, ISO 8601.
impressionsintegerExample:1total_impressionsintegerExample:1clicksintegerExample:1total_clicksintegerExample:1click_ratenumberExample:1.5signupsintegerExample:1total_signupsintegerExample:1signup_ratenumberExample:1.5sort_bystringExample:stringdirectionstringExample:stringvariantsarray of objectsShow 13 child attributesHide child attributes
shopify_variant_idstringExample:stringshopify_product_idstringExample:stringproduct_titlestringExample:stringvariant_titlestringExample:stringimage_urlstringExample:stringimpressionsintegerExample:1total_impressionsintegerExample:1clicksintegerExample:1total_clicksintegerExample:1click_ratenumberExample:1.5signupsintegerExample:1total_signupsintegerExample:1signup_ratenumberExample:1.5
metaobjectPagination for the list.
Show 4 child attributesHide child attributes
total_countintegerItems matching the filters, across all pages.
pageintegerPage returned, starting at 1.
per_pageintegerMost items per page.
total_pagesintegerPages available at this per_page; 0 when nothing matches.
Errors
validation_failedThe action refused the request for a reason that is not a single bad field.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl "https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement?shopify_market_id=gid%3A%2F%2Fshopify%2FMarket%2F12345&shopify_variant_ids=45000000001&sort_by=impressions" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement?shopify_market_id=gid%3A%2F%2Fshopify%2FMarket%2F12345&shopify_variant_ids=45000000001&sort_by=impressions", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement?shopify_market_id=gid%3A%2F%2Fshopify%2FMarket%2F12345&shopify_variant_ids=45000000001&sort_by=impressions",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/reports/engagement?shopify_market_id=gid%3A%2F%2Fshopify%2FMarket%2F12345&shopify_variant_ids=45000000001&sort_by=impressions")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"pixel_active": true,
"window": {
"from": "2026-01-15",
"to": "2026-01-15"
},
"impressions": 1,
"total_impressions": 1,
"clicks": 1,
"total_clicks": 1,
"click_rate": 1.5,
"signups": 1,
"total_signups": 1,
"signup_rate": 1.5,
"sort_by": "string",
"direction": "string",
"variants": [
{
"shopify_variant_id": "string",
"shopify_product_id": "string",
"product_title": "string",
"variant_title": "string",
"image_url": "string",
"impressions": 1,
"total_impressions": 1,
"clicks": 1,
"total_clicks": 1,
"click_rate": 1.5,
"signups": 1,
"total_signups": 1,
"signup_rate": 1.5
}
],
"meta": {
"total_count": 1,
"page": 1,
"per_page": 1,
"total_pages": 1
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}