Skip to content

Update product settings

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

PATCH/back_in_stock/products

Costs 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-Keystring

    A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • widget_template_idinteger, nullable

    Widget template to use, from GET /back_in_stock/widget_templates, or null for the global widget design.

  • targetsarray of objects

    Required. 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_idstring

      Shopify product gid. On its own it addresses ALL variants of the product.

    • shopify_variant_idstring

      Shopify 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 of always_showwhen_out_of_stocknever_show
  • restock_messagestring

    Free text shown under the notify-me button, e.g. "Back in stock March 15". Send "" to clear it.

  • enable_customizationboolean

    Turn 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_disabledboolean

    true 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_enabledboolean

    Turns 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_customizationboolean
    Example: true
  • automatic_alerts_disabledboolean
    Example: false
  • updated_countinteger
    Example: 1
  • created_countinteger
    Example: 0
  • unmatchedarray of anys
  • productsarray of objects
    Show 16 child attributesHide child attributes
    • shopify_product_idstring
      Example: gid://shopify/Product/8784906035384
    • shopify_variant_idstring
      Example: gid://shopify/ProductVariant/47284734423096
    • product_titlestring
      Example: Trail Shoe
    • variant_titlestring
      Example: Blue / Medium
    • skustring
      Example: TS-BLU-M
    • product_statusnull
      Example: active
    • image_urlstring
      Example: https://cdn.shopify.com/s/files/1/0712/3456/7890/files/tr…
    • button_visibilitystring
      Example: when_out_of_stock
    • automatic_alerts_disabledboolean
      Example: false
    • restock_messagestring, nullable
      Example: Back in stock March 15
    • widget_template_idinteger, nullable
    • widget_template_namestring, nullable
    • pending_signupsinteger
      Example: 42
    • total_signupsinteger
      Example: 57
    • units_sold_via_back_in_stockinteger
      Example: 9
    • back_in_stock_revenuestring
      Example: 1170.00
  • per_product_customization_enabledboolean
  • warningsarray of strings

    Notices about the request that did not stop it, such as a deprecated parameter. Absent when there are none.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The action refused the request for a reason that is not a single bad field.

502
shopify_error

A Shopify call the operation needs failed after the operation had started.

503
upstream_unavailable

A 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.

PATCH/back_in_stock/products
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
  }'
Response
{
  "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"
    }
  ]
}