Get product settings
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/productsCosts 1 rate-limit point · Rate limits
Read per-product back-in-stock configuration: notify-me button visibility (always_show / when_out_of_stock / never_show), restock message and assigned widget template (widget_template_id, from GET /back_in_stock/widget_templates) for each variant, plus whether the shop-level per-product customization toggle is on. Each row also has the variant's pending and total signups (count_by as on the dashboard) and its lifetime back-in-stock units sold and revenue. Without search, rows are the variants STOQ has activity for (signups, per-product settings, offers), sorted by pending signups, most first. search (product name, variant title, SKU, product URL or id) also looks the term up in the Shopify catalog: matching variants STOQ has no row for come after the STOQ rows, with default settings and zero counts. Every row has has_stoq_activity; a search response has catalog_searched (false when the catalog was skipped or could not be reached). Filter with shopify_product_id, shopify_variant_id, overrides_only=true or has_waitlist=true; the last two only match STOQ rows, so they skip the catalog. Shopify ids are gids both ways, e.g. "gid://shopify/ProductVariant/123".
Any of sort, group_by, after, product_status, button_visibility, restock_message or restock_message_query lists the dashboard's Products tab instead: the whole Shopify catalog, sorted by sort (title_asc, the default, title_desc, created_desc, created_asc), limit rows per page (default 20, max 100), search matching title or SKU. product_status is a comma list of active, draft, archived, unlisted. button_visibility (comma list of the three values) and restock_message (has or none) with restock_message_query (text the message contains) only match variants STOQ has a row for, as on the tab; with them product_status_filter_skipped is true when product statuses could not be checked and the status filter was left out. group_by=product returns products, each with its variants. Pass the response's end_cursor as after for the next page while has_next_page is true. shopify_product_id, shopify_variant_id, overrides_only and has_waitlist cannot be combined with these.
Also searched aswhich products have custom notify me settingsper product back in stock configproduct button visibilityproducts tab settings
Query parameters
overrides_onlybooleanWhen true, only variants with their own button visibility, restock message or widget template.
has_waitlistbooleanWhen true, only variants with at least one pending signup.
count_bystringCount waiting shoppers once per customer or once per signup. Default is the shop's dashboard setting.
One ofcustomerssignupssortstringOrder of the catalog listing. Default title_asc. Switches to the catalog listing.
One oftitle_asctitle_desccreated_desccreated_ascgroup_bystringSet to product to return products, each with its variants. Switches to the catalog listing.
One ofvariantproductrestock_messagestringOnly variants that have (has) or lack (none) a restock message. Switches to the catalog listing.
One ofhasnoneshopify_product_idstringOnly variants of this Shopify product, as a gid. Not combinable with the catalog listing filters.
shopify_variant_idstringOnly this Shopify variant, as a gid. Not combinable with the catalog listing filters.
limitintegerRows to return. Default 100, max 250; in the catalog listing default 20, max 100.
searchstringText to match against product name, variant title, SKU, product URL or id; also searches the Shopify catalog.
afterstringCursor for the next catalog page, the end_cursor of the previous response. Switches to the catalog listing.
product_statusstringComma-separated product statuses to keep, from active, draft, archived and unlisted. Switches to the catalog listing.
button_visibilitystringComma-separated button visibilities to keep, from always_show, when_out_of_stock and never_show. Switches to the catalog listing.
restock_message_querystringOnly variants whose restock message contains this text. Switches to the catalog listing.
Returns
per_product_customization_enabledbooleanExample:trueshop_alerts_enabledbooleanExample:truecurrencynullISO 4217 code of the currency the money amounts in this response are in: the order's for an order, else the shop's. Null when it is not known.
count_bystringExample:signupsproductsarray of objectsShow 19 child attributesHide child attributes
shopify_product_idstringExample:gid://shopify/Product/8784906035384shopify_variant_idstring, nullableExample:gid://shopify/ProductVariant/47284734423096product_titlestringExample:Trail Shoevariant_titlestring, nullableExample:Blue / MediumskustringExample:TS-BLU-Mproduct_statusstring, nullableExample:activeimage_urlstring, nullableExample:https://cdn.shopify.com/s/files/1/0712/3456/7890/files/tr…button_visibilitystringExample:when_out_of_stockautomatic_alerts_disabledbooleanExample:falserestock_messagestring, nullablewidget_template_idnullwidget_template_namenullpending_signupsintegerExample:42total_signupsintegerExample:57units_sold_via_back_in_stockintegerExample:9back_in_stock_revenuestringExample:1170.00has_stoq_activitybooleanExample:truevariants_countintegervariantsarray of objectsShow 17 child attributesHide child attributes
shopify_product_idstringshopify_variant_idstringproduct_titlestringvariant_titlestringskustringproduct_statusstringimage_urlstringbutton_visibilitystringautomatic_alerts_disabledbooleanrestock_messagestring, nullablewidget_template_idnullwidget_template_namenullpending_signupsintegertotal_signupsintegerunits_sold_via_back_in_stockintegerback_in_stock_revenuestringhas_stoq_activityboolean
catalog_searchedbooleanhas_next_pagebooleanend_cursorstring, nullableproduct_status_filter_skippedboolean
Errors
invalid_paramsOne or more fields failed the action's schema.
validation_failedThe action refused the request for a reason that is not a single bad field.
shopify_errorA Shopify call the operation needs failed after the operation had started.
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/products" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/products", {
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/products",
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/products")
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/products?count_by=customers&sort=title_asc&group_by=variant" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/products?count_by=customers&sort=title_asc&group_by=variant", {
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/products?count_by=customers&sort=title_asc&group_by=variant",
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/products?count_by=customers&sort=title_asc&group_by=variant")
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){
"per_product_customization_enabled": true,
"shop_alerts_enabled": true,
"currency": "USD",
"count_by": "signups",
"products": [
{
"shopify_product_id": "gid://shopify/Product/8784906035384",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"product_title": "Trail Shoe",
"variant_title": "Blue / Medium",
"sku": "TS-BLU-M",
"product_status": "active",
"image_url": "https://cdn.shopify.com/s/files/1/0712/3456/7890/files/trail-shoe-blue.jpg",
"button_visibility": "when_out_of_stock",
"automatic_alerts_disabled": false,
"restock_message": null,
"widget_template_id": null,
"widget_template_name": null,
"pending_signups": 42,
"total_signups": 57,
"units_sold_via_back_in_stock": 9,
"back_in_stock_revenue": "1170.00",
"has_stoq_activity": true
},
{
"shopify_product_id": "gid://shopify/Product/8784906035384",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734455864",
"product_title": "Trail Shoe",
"variant_title": "Blue / Large",
"sku": "TS-BLU-L",
"product_status": "active",
"image_url": "https://cdn.shopify.com/s/files/1/0712/3456/7890/files/trail-shoe-blue.jpg",
"button_visibility": "when_out_of_stock",
"automatic_alerts_disabled": false,
"restock_message": null,
"widget_template_id": null,
"widget_template_name": null,
"pending_signups": 18,
"total_signups": 18,
"units_sold_via_back_in_stock": 0,
"back_in_stock_revenue": "0.00",
"has_stoq_activity": true
}
]
}{
"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
}
]
}