Skip to content

Update delivery settings

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

PATCH/back_in_stock/settings/delivery

Costs 2 rate-limit points · Rate limits

Update back-in-stock delivery settings (batching, stock threshold, locations, any-variant, password-protected sending, alerts on publish). Market setup and market-based alerts are PATCH /account/markets.

Deep partial. Toggles set via this PATCH: batching.enabled, locations.filter_enabled, any_variant.enabled: e.g. { batching: { enabled: true } }. batching.mode is an enum: 'multiplier' (batch size = restocked quantity x batching.multiplier) or 'fixed' (batch size = batching.batch_size); batching.wait_hours is the wait between batches. stock_threshold is the minimum restocked quantity before notifications send (>= 1). any_variant.all_products is a boolean: when true, any-variant alerts apply to every product and any_variant.product_ids is ignored; when false, only the listed products qualify. locations.shopify_location_ids and any_variant.shopify_product_ids are arrays of Shopify gids and are replaced wholesale when present. send_while_password_protected is a boolean: false (default) holds back-in-stock alerts while the storefront password is on (signups stay pending for the next restock); true sends anyway. alert_on_publish also alerts when a product is published.

Also searched asedit delivery settingschange delivery settingsbatch notificationsenable batchingturn on batchingdisable batchingturn off batchingsend all at onceset batch sizeset batching multiplierset batching modeset wait between batchesset stock thresholdset minimum stock to notifyonly notify when 5 in stockrequire minimum quantity before notifyingfilter by locationenable location filterdisable location filterset notification locationsonly count inventory at locationsnotify for any variantenable any variant notificationsdisable any variant notificationsnotify when any variant restockssend alerts while store is password protectedhold alerts while store is password protectedalert when a product is publishednotify customers when a product is published

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

  • batchingobject

    How a restock notifies the waitlist in batches.

    Show 5 child attributesHide child attributes
    • enabledboolean

      Notify customers in batches when a product is restocked, rather than the whole waitlist at once.

    • modestring

      "multiplier" sends restocked quantity x multiplier per batch ("Per unit of stock"); "fixed" sends batch_size per batch.

      One of multiplierfixed
    • multiplierinteger

      Notification multiplier. Used while mode is "multiplier".

    • batch_sizeinteger

      How many customers each batch notifies. Used while mode is "fixed".

    • wait_hoursinteger

      Hours to wait before sending the next batch.

  • stock_thresholdinteger

    Minimum restock quantity before any alert sends. Must be 1 or more.

  • locationsobject

    Location-based alerts.

    Show 2 child attributesHide child attributes
    • filter_enabledboolean

      Location-based alerts: only count stock at the locations listed below.

    • shopify_location_idsarray of strings

      Shopify location gids to count stock at, e.g. "gid://shopify/Location/123". REPLACES the stored list.

  • any_variantobject

    Any-variant alerts.

    Show 3 child attributesHide child attributes
    • enabledboolean

      Notify customers when any product option is restocked, not only the option they asked for.

    • all_productsboolean

      True applies that to all products; false to the selected products only.

    • shopify_product_idsarray of strings

      Shopify product gids it applies to, e.g. "gid://shopify/Product/123". REPLACES the stored list. Ignored while all_products is true.

  • send_while_password_protectedboolean

    Send alerts while the store is password protected.

  • alert_on_publishboolean

    Also alert customers when a product they wait for is published to the Online Store, not only when it restocks.

Returns

  • batchingobject
    Show 5 child attributesHide child attributes
    • enabledboolean
      Example: true
    • modestring
      Example: fixed
    • multiplierinteger
      Example: 100
    • batch_sizeinteger
      Example: 50
    • wait_hoursinteger
      Example: 2
  • stock_thresholdinteger
    Example: 3
  • locationsobject
    Show 2 child attributesHide child attributes
    • filter_enabledboolean
      Example: true
    • shopify_location_idsarray of strings
  • any_variantobject
    Show 3 child attributesHide child attributes
    • enabledboolean
      Example: true
    • all_productsboolean
      Example: false
    • shopify_product_idsarray of strings
  • send_while_password_protectedboolean
    Example: false
  • alert_on_publishboolean
    Example: true

Errors

404
not_found

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

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 request failed validation.

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/settings/delivery
curl -X PATCH "https://app.stoqapp.com/api/v2/external/back_in_stock/settings/delivery" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batching": {
      "enabled": true,
      "mode": "fixed",
      "batch_size": 50,
      "wait_hours": 2
    },
    "stock_threshold": 3
  }'
Response
{
  "batching": {
    "enabled": true,
    "mode": "fixed",
    "multiplier": 100,
    "batch_size": 50,
    "wait_hours": 2
  },
  "stock_threshold": 3,
  "locations": {
    "filter_enabled": true,
    "shopify_location_ids": [
      "gid://shopify/Location/71234568281"
    ]
  },
  "any_variant": {
    "enabled": true,
    "all_products": false,
    "shopify_product_ids": [
      "gid://shopify/Product/8784906035384"
    ]
  },
  "send_while_password_protected": false,
  "alert_on_publish": true
}