Retrieve engagement

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

GET/back_in_stock/reports/engagement

Costs 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

fromstring
tostring
shopify_market_idstring
shopify_variant_idsarray
sort_bystring
directionstring
pagestring
per_pagestring

Errors

401

Missing or invalid X-Auth-Token.

422

The request failed validation.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

Example

GET/back_in_stock/reports/engagement

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)

GET/back_in_stock/reports/engagement

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" \
  -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", {
  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",
    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")
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)

Response

No body

{
  "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
    }
  ]
}