---
title: "Get product settings"
description: "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_t"
url: https://docs.stoqapp.com/v2-reference/back-in-stock-products/get-product-settings/
api: "API v2 reference"
method: GET
path: "/back_in_stock/products"
---

# Get product settings

`GET https://app.stoqapp.com/api/v2/external/back_in_stock/products`

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`](https://docs.stoqapp.com/v2-reference/back-in-stock-widget-templates/list-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. &quot;gid://shopify/ProductVariant/123&quot;.

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

## Query parameters

- `overrides_only` (boolean): When true, only variants with their own button visibility, restock message or widget template.
- `has_waitlist` (boolean): When true, only variants with at least one pending signup.
- `count_by` (string): Count waiting shoppers once per customer or once per signup. Default is the shop's dashboard setting. One of: `customers`, `signups`.
- `sort` (string): Order of the catalog listing. Default title_asc. Switches to the catalog listing. One of: `title_asc`, `title_desc`, `created_desc`, `created_asc`.
- `group_by` (string): Set to product to return products, each with its variants. Switches to the catalog listing. One of: `variant`, `product`.
- `restock_message` (string): Only variants that have (has) or lack (none) a restock message. Switches to the catalog listing. One of: `has`, `none`.
- `shopify_product_id` (string): Only variants of this Shopify product, as a gid. Not combinable with the catalog listing filters.
- `shopify_variant_id` (string): Only this Shopify variant, as a gid. Not combinable with the catalog listing filters.
- `limit` (integer): Rows to return. Default 100, max 250; in the catalog listing default 20, max 100.
- `search` (string): Text to match against product name, variant title, SKU, product URL or id; also searches the Shopify catalog.
- `after` (string): Cursor for the next catalog page, the end_cursor of the previous response. Switches to the catalog listing.
- `product_status` (string): Comma-separated product statuses to keep, from active, draft, archived and unlisted. Switches to the catalog listing.
- `button_visibility` (string): Comma-separated button visibilities to keep, from always_show, when_out_of_stock and never_show. Switches to the catalog listing.
- `restock_message_query` (string): Only variants whose restock message contains this text. Switches to the catalog listing.

## Returns

- `per_product_customization_enabled` (boolean): e.g. `true`
- `shop_alerts_enabled` (boolean): e.g. `true`
- `currency` (null): 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_by` (string): e.g. `signups`
- `products` (array of objects)
  - `shopify_product_id` (string): e.g. `gid://shopify/Product/8784906035384`
  - `shopify_variant_id` (string, nullable): e.g. `gid://shopify/ProductVariant/47284734423096`
  - `product_title` (string): e.g. `Trail Shoe`
  - `variant_title` (string, nullable): e.g. `Blue / Medium`
  - `sku` (string): e.g. `TS-BLU-M`
  - `product_status` (string, nullable): e.g. `active`
  - `image_url` (string, nullable): e.g. `https://cdn.shopify.com/s/files/1/0712/3456/7890/files/tr…`
  - `button_visibility` (string): e.g. `when_out_of_stock`
  - `automatic_alerts_disabled` (boolean): e.g. `false`
  - `restock_message` (string, nullable)
  - `widget_template_id` (null)
  - `widget_template_name` (null)
  - `pending_signups` (integer): e.g. `42`
  - `total_signups` (integer): e.g. `57`
  - `units_sold_via_back_in_stock` (integer): e.g. `9`
  - `back_in_stock_revenue` (string): e.g. `1170.00`
  - `has_stoq_activity` (boolean): e.g. `true`
  - `variants_count` (integer)
  - `variants` (array of objects)
    - `shopify_product_id` (string)
    - `shopify_variant_id` (string)
    - `product_title` (string)
    - `variant_title` (string)
    - `sku` (string)
    - `product_status` (string)
    - `image_url` (string)
    - `button_visibility` (string)
    - `automatic_alerts_disabled` (boolean)
    - `restock_message` (string, nullable)
    - `widget_template_id` (null)
    - `widget_template_name` (null)
    - `pending_signups` (integer)
    - `total_signups` (integer)
    - `units_sold_via_back_in_stock` (integer)
    - `back_in_stock_revenue` (string)
    - `has_stoq_activity` (boolean)
- `catalog_searched` (boolean)
- `has_next_page` (boolean)
- `end_cursor` (string, nullable)
- `product_status_filter_skipped` (boolean)

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Examples

### Get product settings

```sh
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/products" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

### Get product settings filtered by count_by, sort and group_by

```sh
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/products?count_by=customers&sort=title_asc&group_by=variant" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: example response shown.

```json
{
  "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
    }
  ]
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

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

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

