Get the engagement report
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/reports/engagementCosts 1 rate-limit point · Rate limits
Preorder button engagement: impressions, add-to-carts, add-to-cart rate, orders and order rate, shop-wide and per variant: the merchant's Products > Engagement view.
Rates use unique shoppers; total_* fields count every event. order_rate can exceed 1.0: orders are placed preorder orders, a different denominator than unique add-to-carts. from/to default to the shop's lifetime. variants is paged and sorted by sort_by (default impressions); shopify_variant_ids narrows it. 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 aspreorder engagementpreorder funneladd to cart ratebutton engagementpreorder performance
Query parameters
fromstringFirst day of the window, as YYYY-MM-DD. Defaults to the day the shop installed STOQ.
tostringLast day of the window, as YYYY-MM-DD. Default today.
shopify_market_idstringOnly engagement in this Shopify market, as a market gid (gid://shopify/Market/<id>) or numeric id.
shopify_variant_idsarrayOnly these variants in the per-variant rows, as Shopify variant gids or numeric ids (an array or one comma-separated string, up to 250).
sort_bystringColumn to sort the variant rows by. Default impressions.
One ofimpressionsadd_to_cartsadd_to_cart_ratetotal_impressionstotal_add_to_cartsDefault"impressions"directionstringSort order of the rows. Default desc.
One ofascdescDefault"desc"pageintegerPage of rows to return, starting at 1.
Default1per_pageintegerVariant rows per page, 1 to 250. Default 50, or 250 when shopify_variant_ids is sent.
Default50
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:1add_to_cartsintegerExample:1total_add_to_cartsintegerExample:1add_to_cart_rateintegerExample:1ordersintegerExample:1order_rateintegerExample:1sort_bystringExample:stringdirectionstringExample:stringvariantsarray of objectsShow 12 child attributesHide child attributes
shopify_variant_idstringExample:stringshopify_product_idstringExample:stringproduct_titlestringExample:stringvariant_titlestringExample:stringimage_urlstringExample:stringimpressionsintegerExample:1total_impressionsintegerExample:1add_to_cartsintegerExample:1total_add_to_cartsintegerExample:1add_to_cart_ratenumberExample:1.5ordersintegerExample:1order_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/preorders/reports/engagement" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/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/preorders/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/preorders/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/preorders/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/preorders/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/preorders/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/preorders/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,
"add_to_carts": 1,
"total_add_to_carts": 1,
"add_to_cart_rate": 1,
"orders": 1,
"order_rate": 1,
"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,
"add_to_carts": 1,
"total_add_to_carts": 1,
"add_to_cart_rate": 1.5,
"orders": 1,
"order_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
}
]
}