Update products

PATCH

/back_in_stock/products

curl --request PATCH \
  --url https://app.stoqapp.com/api/v2/external/back_in_stock/products \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "targets": "string", "button_visibility": "string", "restock_message": "string", "template": "string", "enable_customization": "string", "automatic_alerts_enabled": true, "per_product_customization_enabled": true }'

• Production

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. template is a back-in-stock template name or id, or “default” to fall back to the global widget design. automatic_alerts_enabled (true/false) directly sets whether this variant receives an automatic back-in-stock alert on restock – the same control as the variant’s own “Enable/Disable alerts” button, independent of button_visibility. Use this to fix a variant showing “Disabled” for automatic alerts in get_bis_products (get_bis_products.automatic_alerts_enabled), not button_visibility. If both button_visibility: “always_show” and automatic_alerts_enabled are sent in the same call, automatic_alerts_enabled 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_enabled 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”).

Note: 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.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

object

targets

button_visibility

restock_message

template

enable_customization

automatic_alerts_enabled

per_product_customization_enabled

Example

{
  "targets": "string",
  "button_visibility": "string",
  "restock_message": "string",
  "template": "string",
  "enable_customization": "string",
  "automatic_alerts_enabled": true,
  "per_product_customization_enabled": true
}

Responses

200

Success — the updated resource.

Media typeapplication/json

object

Example ^generated

{}

202

Accepted — async/bulk work was queued. Poll the returned job.

Media typeapplication/json

Returned for async/bulk work — poll the job until it reaches a terminal state.

object

job_id

string

status_url

string

Example

{
  "job_id": "job_a1b2c3",
  "status_url": "/api/v2/external/jobs/job_a1b2c3"
}

401

Missing or invalid X-Auth-Token.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Unauthorized"
  ]
}

422

The request failed validation.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "name is required"
  ]
}

429

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

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Rate limit exceeded"
  ]
}