Settings - STOQ Docs

Back-in-stock settings are a shop-level singleton — there is no :id in any path. The surface is split into five capabilities, and everything is GET + PATCH; there are no named actions (no setting here has side effects beyond writing configuration, so the granularity convention means no enable_x/set_y endpoints).

Path prefix: /back_in_stock/settings

Endpoints

Method	Path	Capability
`GET`	`/back_in_stock/settings`	All five blocks in one response
`PATCH`	`/back_in_stock/settings`	Any combination of capability blobs
`GET` / `PATCH`	`/back_in_stock/settings/channels`	Which channels send (email, SMS, push)
`GET` / `PATCH`	`/back_in_stock/settings/delivery`	Batching, stock threshold, locations, any-variant
`GET` / `PATCH`	`/back_in_stock/settings/compliance`	GDPR double opt-in
`GET` / `PATCH`	`/back_in_stock/settings/tagging`	Order tag on recovered orders
`GET` / `PATCH`	`/back_in_stock/settings/alerts`	Merchant alerts + scheduled report emails

PATCH semantics

Every PATCH is deep partial — send only the keys you want to change, nested however deep. The top-level PATCH /back_in_stock/settings accepts any combination of capability blobs and delegates each to the capability's own update; validation errors from all blobs are accumulated into one response.

curl -X PATCH 'https://app.stoqapp.com/api/v2/external/back_in_stock/settings' \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channels":{"sms":{"enabled":true}},"compliance":{"optin_required":true}}'

Each capability PATCH returns the capability's full block after the write; the top-level PATCH returns all five.

Channels

Which notification channels are enabled.

{
  "email": { "enabled": true },
  "sms": { "enabled": false },
  "push": { "enabled": true }
}

PATCH — "enable SMS":

{ "sms": { "enabled": true } }

Warning

Enabling SMS for the first time triggers a restricted-content verification check — sends may be held until the shop is verified.

Delivery

How and when notifications go out. Four sub-concerns:

{
  "batching": {
    "enabled": false,
    "mode": "multiplier",
    "multiplier": 3,
    "batch_size": 100,
    "wait_hours": 24
  },
  "stock_threshold": 1,
  "locations": { "filter_enabled": false, "location_ids": [] },
  "any_variant": { "enabled": false, "product_ids": [] }
}

Field	Notes
`batching.enabled`	Send in batches instead of all at once
`batching.mode`	`multiplier` — batch size = restocked quantity × `multiplier`; `fixed` — batch size = `batch_size`
`batching.wait_hours`	Wait between batches
`stock_threshold`	Minimum restocked quantity before notifications send at all (≥ 1)
`locations.filter_enabled`	Only count inventory at the listed locations
`locations.location_ids`	Shopify numeric location ids — replaced wholesale when present
`any_variant.enabled`	Notify signups when any variant of the product restocks
`any_variant.product_ids`	Products the any-variant behavior applies to — replaced wholesale when present

PATCH — "batch notifications" (fixed batches of 100, 24h apart):

{ "batching": { "enabled": true, "mode": "fixed", "batch_size": 100, "wait_hours": 24 } }

Compliance

GDPR double opt-in. When enabled, signups must confirm via email before they are eligible for notifications.

{ "optin_required": false }

PATCH — "require double opt-in":

{ "optin_required": true }

The per-signup confirmation state surfaces on the signup's optin block.

Tagging

The tag applied to Shopify orders attributed to a back-in-stock notification.

{
  "order_tags": { "enabled": false, "tag": "STOQ-back-in-stock" }
}

PATCH — "tag recovered orders":

{ "order_tags": { "enabled": true, "tag": "restock-recovered" } }

tag is a single tag (default STOQ-back-in-stock).

Alerts

Merchant-facing alerting and scheduled report emails. Two sub-concerns:

{
  "signups_threshold": { "count": 10, "notify": true },
  "scheduled_reports": { "daily": false, "weekly": true, "monthly": false }
}

Field	Notes
`signups_threshold.count`	Per-variant pending-signup count that triggers the merchant alert email
`signups_threshold.notify`	Whether the threshold alert sends at all
`scheduled_reports.daily` / `weekly` / `monthly`	Summary report emails on each cadence

PATCH — weekly report on, threshold alert at 25 signups:

{ "signups_threshold": { "count": 25, "notify": true }, "scheduled_reports": { "weekly": true } }

Full settings shape

GET /back_in_stock/settings returns all five blocks under their capability keys:

{
  "channels": { "email": { "enabled": true }, "sms": { "enabled": false }, "push": { "enabled": true } },
  "delivery": {
    "batching": { "enabled": false, "mode": "multiplier", "multiplier": 3, "batch_size": 100, "wait_hours": 24 },
    "stock_threshold": 1,
    "locations": { "filter_enabled": false, "location_ids": [] },
    "any_variant": { "enabled": false, "product_ids": [] }
  },
  "compliance": { "optin_required": false },
  "tagging": { "order_tags": { "enabled": false, "tag": "STOQ-back-in-stock" } },
  "alerts": {
    "signups_threshold": { "count": 10, "notify": true },
    "scheduled_reports": { "daily": false, "weekly": false, "monthly": false }
  }
}