Skip to content

Get product settings

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

GET/back_in_stock/products

Costs 1 rate-limit point · Rate limits

Read per-product back-in-stock configuration: notify-me button visibility (always_show / when_out_of_stock / never_show), restock message and assigned widget template (widget_template_id, from GET /back_in_stock/widget_templates) for each variant, plus whether the shop-level per-product customization toggle is on. Each row also has the variant's pending and total signups (count_by as on the dashboard) and its lifetime back-in-stock units sold and revenue. Without search, rows are the variants STOQ has activity for (signups, per-product settings, offers), sorted by pending signups, most first. search (product name, variant title, SKU, product URL or id) also looks the term up in the Shopify catalog: matching variants STOQ has no row for come after the STOQ rows, with default settings and zero counts. Every row has has_stoq_activity; a search response has catalog_searched (false when the catalog was skipped or could not be reached). Filter with shopify_product_id, shopify_variant_id, overrides_only=true or has_waitlist=true; the last two only match STOQ rows, so they skip the catalog. Shopify ids are gids both ways, e.g. "gid://shopify/ProductVariant/123".

Any of sort, group_by, after, product_status, button_visibility, restock_message or restock_message_query lists the dashboard's Products tab instead: the whole Shopify catalog, sorted by sort (title_asc, the default, title_desc, created_desc, created_asc), limit rows per page (default 20, max 100), search matching title or SKU. product_status is a comma list of active, draft, archived, unlisted. button_visibility (comma list of the three values) and restock_message (has or none) with restock_message_query (text the message contains) only match variants STOQ has a row for, as on the tab; with them product_status_filter_skipped is true when product statuses could not be checked and the status filter was left out. group_by=product returns products, each with its variants. Pass the response's end_cursor as after for the next page while has_next_page is true. shopify_product_id, shopify_variant_id, overrides_only and has_waitlist cannot be combined with these.

Also searched aswhich products have custom notify me settingsper product back in stock configproduct button visibilityproducts tab settings

Query parameters

  • overrides_onlyboolean

    When true, only variants with their own button visibility, restock message or widget template.

  • has_waitlistboolean

    When true, only variants with at least one pending signup.

  • count_bystring

    Count waiting shoppers once per customer or once per signup. Default is the shop's dashboard setting.

    One of customerssignups
  • sortstring

    Order of the catalog listing. Default title_asc. Switches to the catalog listing.

    One of title_asctitle_desccreated_desccreated_asc
  • group_bystring

    Set to product to return products, each with its variants. Switches to the catalog listing.

    One of variantproduct
  • restock_messagestring

    Only variants that have (has) or lack (none) a restock message. Switches to the catalog listing.

    One of hasnone
  • shopify_product_idstring

    Only variants of this Shopify product, as a gid. Not combinable with the catalog listing filters.

  • shopify_variant_idstring

    Only this Shopify variant, as a gid. Not combinable with the catalog listing filters.

  • limitinteger

    Rows to return. Default 100, max 250; in the catalog listing default 20, max 100.

  • searchstring

    Text to match against product name, variant title, SKU, product URL or id; also searches the Shopify catalog.

  • afterstring

    Cursor for the next catalog page, the end_cursor of the previous response. Switches to the catalog listing.

  • product_statusstring

    Comma-separated product statuses to keep, from active, draft, archived and unlisted. Switches to the catalog listing.

  • button_visibilitystring

    Comma-separated button visibilities to keep, from always_show, when_out_of_stock and never_show. Switches to the catalog listing.

  • restock_message_querystring

    Only variants whose restock message contains this text. Switches to the catalog listing.

Returns

  • per_product_customization_enabledboolean
    Example: true
  • shop_alerts_enabledboolean
    Example: true
  • currencynull

    ISO 4217 code of the currency the money amounts in this response are in: the order's for an order, else the shop's. Null when it is not known.

  • count_bystring
    Example: signups
  • productsarray of objects
    Show 19 child attributesHide child attributes
    • shopify_product_idstring
      Example: gid://shopify/Product/8784906035384
    • shopify_variant_idstring, nullable
      Example: gid://shopify/ProductVariant/47284734423096
    • product_titlestring
      Example: Trail Shoe
    • variant_titlestring, nullable
      Example: Blue / Medium
    • skustring
      Example: TS-BLU-M
    • product_statusstring, nullable
      Example: active
    • image_urlstring, nullable
      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
    • widget_template_idnull
    • widget_template_namenull
    • pending_signupsinteger
      Example: 42
    • total_signupsinteger
      Example: 57
    • units_sold_via_back_in_stockinteger
      Example: 9
    • back_in_stock_revenuestring
      Example: 1170.00
    • has_stoq_activityboolean
      Example: true
    • variants_countinteger
    • variantsarray of objects
      Show 17 child attributesHide child attributes
      • shopify_product_idstring
      • shopify_variant_idstring
      • product_titlestring
      • variant_titlestring
      • skustring
      • product_statusstring
      • image_urlstring
      • button_visibilitystring
      • automatic_alerts_disabledboolean
      • restock_messagestring, nullable
      • widget_template_idnull
      • widget_template_namenull
      • pending_signupsinteger
      • total_signupsinteger
      • units_sold_via_back_in_stockinteger
      • back_in_stock_revenuestring
      • has_stoq_activityboolean
  • catalog_searchedboolean
  • has_next_pageboolean
  • end_cursorstring, nullable
  • product_status_filter_skippedboolean

Errors

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.

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.

GET/back_in_stock/products
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/products" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "per_product_customization_enabled": true,
  "shop_alerts_enabled": true,
  "currency": "USD",
  "count_by": "signups",
  "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": null,
      "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",
      "has_stoq_activity": true
    },
    {
      "shopify_product_id": "gid://shopify/Product/8784906035384",
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734455864",
      "product_title": "Trail Shoe",
      "variant_title": "Blue / Large",
      "sku": "TS-BLU-L",
      "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": null,
      "widget_template_id": null,
      "widget_template_name": null,
      "pending_signups": 18,
      "total_signups": 18,
      "units_sold_via_back_in_stock": 0,
      "back_in_stock_revenue": "0.00",
      "has_stoq_activity": true
    }
  ]
}