Skip to content

Get products in demand

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

GET/back_in_stock/reports/products_in_demand

Costs 1 rate-limit point · Rate limits

The Products in demand table: variants (or products) ranked by back-in-stock demand, with signups created in the window, how many of them are still waiting, and the last request.

The same rows as the dashboard table. total counts signups created in the window; pending counts those of them not yet notified. count_by=customers counts a shopper signed up on several channels once; omitted, it follows the dashboard default, and the response's count_by says which. group_by=product ranks products instead of variants. search matches product title or SKU; vendors, tags and shopify_market_ids are comma-separated lists, as the table's filters. Deleted variants are hidden when the shop's dashboard hides them. image_url is the variant's image, else the product's. Variant rows only: include_inventory=true adds inventory_available, the stock available in the locations the shop's market or location filter allows (summed, null when Shopify has no level), and include_prices=true adds price and compare_at_price in the shop's currency, as the table's Inventory and Price columns. Each asks Shopify once per page. include_totals=true adds totals { pending, total }, the pending and total columns summed over every row the filters keep, not just this page.

Also searched asdemand reportwhat should I restockmost wanted productstop requested variantsproducts in demandrestock priorities

Query parameters

  • group_bystring

    Return a row per variant or per product. Default variant.

    One of variantproduct
  • sort_bystring

    Column to sort rows by. Default pending.

    One of pendingtotallast_requested_at
    Default "pending"
  • directionstring

    Sort direction. Default desc.

    One of ascdesc
    Default "desc"
  • count_bystring

    Count a shopper signed up on several channels once (customers) or each signup (signups). Default is the shop's dashboard setting.

    One of customerssignups
  • include_inventoryboolean

    When true, variant rows include the available stock. Variant rows only.

    Default false
  • include_pricesboolean

    When true, variant rows include price and compare-at price. Variant rows only.

    Default false
  • include_totalsboolean

    When true, the response adds pending and total summed over every row the filters keep.

    Default false
  • fromstring

    Start of the window, an ISO 8601 date or date-time; a bare date starts at midnight in the shop's time zone. Default 30 days ago.

  • tostring

    End of the window, an ISO 8601 date or date-time; a bare date runs to the end of that day in the shop's time zone. Default today.

  • rangestring

    Set to all_time for the shop's whole history instead of from/to.

    One of all_time
  • shopify_market_idsstring

    Comma-separated Shopify market gids or numeric ids to keep.

  • searchstring

    Only rows whose product title or SKU contains this text.

  • vendorsstring

    Comma-separated product vendors to keep.

  • tagsstring

    Comma-separated product tags to keep.

  • pageinteger

    Page of results to return, starting at 1.

    Default 1
  • per_pageinteger

    Rows per page, 1 to 500. Default 25.

    Default 25

Returns

  • windowobject, nullable

    The date range the figures cover. Null when range is all_time.

    Show 2 child attributesHide child attributes
    • fromstring

      Start of the range, ISO 8601.

    • tostring

      End of the range, ISO 8601.

  • group_bystring
    Example: variant
  • sort_bystring
    Example: pending
  • directionstring
    Example: desc
  • count_bystring
    Example: customers
  • rowsarray of objects
    Show 14 child attributesHide child attributes
    • shopify_variant_idstring
      Example: gid://shopify/ProductVariant/47284734423096
    • shopify_product_idstring
      Example: gid://shopify/Product/8784906035384
    • variant_titlestring, nullable
      Example: Blue / Medium
    • product_titlestring, nullable
      Example: Classic Sneaker
    • skustring, nullable
      Example: CS-BLU-M
    • image_urlstring, nullable
    • deletedboolean
    • variants_countinteger
    • pendinginteger
      Example: 47
    • totalinteger
      Example: 89
    • last_requested_atstring
      Example: 2026-06-25T11:30:00Z
    • inventory_availableinteger, nullable
    • pricestring, nullable
    • compare_at_pricestring, nullable
  • metaobject

    Pagination for the list.

    Show 4 child attributesHide child attributes
    • total_countinteger

      Items matching the filters, across all pages.

    • pageinteger

      Page returned, starting at 1.

    • per_pageinteger

      Most items per page.

    • total_pagesinteger

      Pages available at this per_page; 0 when nothing matches.

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.

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/reports/products_in_demand
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/reports/products_in_demand" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "window": {
    "from": "2026-05-26T00:00:00Z",
    "to": "2026-06-25T23:59:59Z"
  },
  "group_by": "variant",
  "sort_by": "pending",
  "direction": "desc",
  "count_by": "customers",
  "rows": [
    {
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
      "shopify_product_id": "gid://shopify/Product/8784906035384",
      "variant_title": "Blue / Medium",
      "product_title": "Classic Sneaker",
      "sku": "CS-BLU-M",
      "pending": 47,
      "total": 89,
      "last_requested_at": "2026-06-25T11:30:00Z"
    },
    {
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734455864",
      "shopify_product_id": "gid://shopify/Product/8784906035384",
      "variant_title": "Red / Large",
      "product_title": "Classic Sneaker",
      "sku": "CS-RED-L",
      "pending": 23,
      "total": 56,
      "last_requested_at": "2026-06-25T09:15:00Z"
    }
  ],
  "meta": {
    "total_count": 287,
    "page": 1,
    "per_page": 50,
    "total_pages": 6
  }
}