Update product settings
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/productsCosts 2 rate-limit points · Rate limits
Update per-product back-in-stock configuration for one or more products or variants (the "Back in stock alerts -> Products" tab). targets is a list; a target with shopify_variant_id changes just that VARIANT, a target with only shopify_product_id changes EVERY variant of that product. The same field values are applied to every target, so send one call per distinct set of values. button_visibility is one of "always_show" (notify-me button shown even while the item is IN stock -- WARNING: this also DISABLES automatic back-in-stock alerts for that variant, so the merchant has to notify signups manually), "when_out_of_stock" (the default: button appears only when out of stock and alerts send automatically) or "never_show" (button hidden on the storefront). restock_message is the free-text note shown under the button (e.g. "Back in stock March 15"); send an empty string to clear it. widget_template_id is a widget template id from GET /back_in_stock/widget_templates, or null to fall back to the global widget design. Target ids are Shopify gids. automatic_alerts_disabled (true/false) directly turns this variant's automatic back-in-stock alert on restock off (true) or on (false) -- the same control as the variant's own "Enable/Disable alerts" button, independent of button_visibility, and the field GET /back_in_stock/products reads back. Send false to fix a variant showing "Disabled" for automatic alerts, not button_visibility. If both button_visibility: "always_show" and automatic_alerts_disabled are sent in the same call, automatic_alerts_disabled wins. Per-product visibility/message/template values only take effect while the shop-level toggle configure_notify_me_enabled is on; when it is off this action refuses rather than store values that would not apply, unless enable_customization: true is passed, which turns the toggle on as part of this change (a no-op when already on). automatic_alerts_disabled is NOT gated by configure_notify_me_enabled -- it applies regardless. per_product_customization_enabled (true/false), sent on its own with no targets, turns that shop-level toggle on or off (off = the tab's "Disable per-product overrides").
Bulk-safe: a single call may address up to 100 targets and writes them in one transaction with the Shopify metafield syncs fired once for the whole batch. A target STOQ has no product_variants row for is looked up in the shop's Shopify catalog; when it is there, its rows are created (one per variant for a product target) and the change is applied to them. Ids in neither are reported in unmatched. Deleting a back-in-stock template clears it from every product/variant it was assigned to (they fall back to the global design); template CRUD lives on the templates capability. automatic_alerts_enabled is the deprecated, inverted name for automatic_alerts_disabled: it is still applied, and the response carries a warning.
Also searched ashide the notify me button on these productsalways show the notify me buttonshow the notify me button even when in stockhide notify me on discontinued productsadd a restock message to a productset a back in stock date on a productclear the restock noteuse a custom back in stock template on this productassign a template to a productper product notify me settingsper product back in stock settingsbutton visibility for a productdisable per product overridesturn off per product customization
Headers
Idempotency-KeystringA fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with
Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
widget_template_idinteger, nullableWidget template to use, from GET /back_in_stock/widget_templates, or null for the global widget design.
targetsarray of objectsRequired. Products/variants to change, as Shopify gids ("gid://shopify/ProductVariant/123", "gid://shopify/Product/45"). get_bis_products returns them; find_products returns the bare number to put after the last slash. A product STOQ has no row for yet is looked up in the Shopify catalog and added. Include shopify_variant_id to change ONE variant; include only shopify_product_id to change EVERY variant of that product.
Show 2 child attributesHide child attributes
shopify_product_idstringShopify product gid. On its own it addresses ALL variants of the product.
shopify_variant_idstringShopify variant gid. When present the change applies to this variant only.
button_visibilitystring"always_show" = notify-me button visible even while IN stock, and automatic back-in-stock alerts are DISABLED for that variant (the merchant must notify signups manually): warn the merchant before proposing it. "when_out_of_stock" = the default; button shows only when out of stock and alerts send automatically. "never_show" = button hidden on the storefront.
One ofalways_showwhen_out_of_stocknever_showrestock_messagestringFree text shown under the notify-me button, e.g. "Back in stock March 15". Send "" to clear it.
enable_customizationbooleanTurn the shop-level per-product customization toggle ON as part of this change. Required when it is currently off: without it the call is refused, because the values would be stored but ignored on the storefront. No-op when already on.
automatic_alerts_disabledbooleantrue turns automatic back-in-stock alert delivery off for these variants, false turns it back on: the same control as the variant's own "Enable/Disable alerts" button, independent of button_visibility, and the same name and polarity get_bis_products and GET /back_in_stock/products read. Send false to fix a variant read as automatic_alerts_disabled: true. It does not turn on the shop-wide alerts switch, which makes every variant read true while it is off. Not gated by enable_customization. If sent together with button_visibility: "always_show", this value wins over the implicit alerts-off side effect.
per_product_customization_enabledbooleanTurns the shop-level per-product customization toggle on (true) or off (false). Off is the Products tab's "Disable per-product overrides": every product follows the global settings again, and the stored per-product values are kept but ignored on the storefront. Send it on its own, with no targets; to turn it on while changing products, use enable_customization.
Returns
enabled_per_product_customizationbooleanExample:trueautomatic_alerts_disabledbooleanExample:falseupdated_countintegerExample:1created_countintegerExample:0unmatchedarray of anysproductsarray of objectsShow 16 child attributesHide child attributes
shopify_product_idstringExample:gid://shopify/Product/8784906035384shopify_variant_idstringExample:gid://shopify/ProductVariant/47284734423096product_titlestringExample:Trail Shoevariant_titlestringExample:Blue / MediumskustringExample:TS-BLU-Mproduct_statusnullExample:activeimage_urlstringExample:https://cdn.shopify.com/s/files/1/0712/3456/7890/files/tr…button_visibilitystringExample:when_out_of_stockautomatic_alerts_disabledbooleanExample:falserestock_messagestring, nullableExample:Back in stock March 15widget_template_idinteger, nullablewidget_template_namestring, nullablepending_signupsintegerExample:42total_signupsintegerExample:57units_sold_via_back_in_stockintegerExample:9back_in_stock_revenuestringExample:1170.00
per_product_customization_enabledbooleanwarningsarray of stringsNotices about the request that did not stop it, such as a deprecated parameter. Absent when there are none.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
conflictThe request is well formed, but the resource's current state does not allow it.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
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.
upstream_unavailableA service the answer depends on did not respond in time.
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 -X PATCH "https://app.stoqapp.com/api/v2/external/back_in_stock/products" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"targets": [
{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096"
}
],
"restock_message": "Back in stock March 15",
"enable_customization": true
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/products", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"targets": [
{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096"
}
],
"restock_message": "Back in stock March 15",
"enable_customization": true
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/back_in_stock/products",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"targets": [
{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096"
}
],
"restock_message": "Back in stock March 15",
"enable_customization": True
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/products")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
targets: [
{
shopify_variant_id: "gid://shopify/ProductVariant/47284734423096"
}
],
restock_message: "Back in stock March 15",
enable_customization: true
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"enabled_per_product_customization": true,
"automatic_alerts_disabled": false,
"updated_count": 1,
"created_count": 0,
"unmatched": [],
"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": "Back in stock March 15",
"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"
}
]
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"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
}
]
}