---
title: "List an offer's variants"
description: "List the variants on a preorder offer, as the offer's Products table shows them, paginated."
url: https://docs.stoqapp.com/v2-reference/preorders-offers/list-an-offers-variants/
api: "API v2 reference"
method: GET
path: "/preorders/offers/{id}/products/variants"
---

# List an offer's variants

`GET https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/products/variants`

List the variants on a preorder offer, as the offer's Products table shows them, paginated.

**Note:** On an offer with batches on, each row has batch_progress (units sold and the limit enforced per batch, and the batch on sale now) and batch_limits (the variant's own per-batch limits). max_count is the variant's own limit, the one PATCH writes; quantity_limit is the read-only limit that applies (the batches' total on a batch offer, where max_count is kept but not enforced). search matches product title, variant title and SKU. sort is one of attached, title, title_asc, title_desc, created_asc, created_desc, added_asc, added_desc, sold_asc, sold_desc (default attached, the attach order; title is title_asc). product_status keeps products in active, draft, archived, unlisted (comma-separated); when a product's status can't be read from Shopify the filter is skipped and product_status_filter_skipped is true. limit_reached=true keeps variants at their quantity limit. product.status is the stored status; include_statuses=true reads the ones not stored yet from Shopify (products[].status when grouped). group_by=product returns products (shopify_product_id, title, image_url, variant_count, variants) instead of variants and pages by product, so a product's variants never split across pages: per_page counts products and meta has total_products and total_variants. exclude_discarded=true leaves out variants deleted from the catalog (discarded: true). include_inventory=true adds each row's live Shopify inventory_quantity, inventory_policy and product.tags. The filters inventory (zero_or_below | positive), inventory_policy (DENY | CONTINUE; lowercase is deprecated), product_tag and exclude_product_tag imply include_inventory and apply to each page after the read, so a page can hold fewer rows than per_page; keep paging while meta.page &lt; meta.total_pages.

## Path parameters

- `id` (string, required): The offer's ID, from [`GET /preorders/offers`](https://docs.stoqapp.com/v2-reference/preorders-offers/list-offers/).

## Query parameters

- `sort` (string): Sort order. Default attached (the order variants were added); title is the same as title_asc. One of: `attached`, `title`, `title_asc`, `title_desc`, `created_asc`, `created_desc`, `added_asc`, `added_desc`, `sold_asc`, `sold_desc`.
- `limit_reached` (boolean): true keeps only variants that have reached their quantity limit.
- `include_statuses` (boolean): true reads product statuses not stored yet from Shopify. Default false.
- `group_by` (string): product returns products with their variants and pages by product instead of by variant. One of: `product`.
- `exclude_discarded` (boolean): true leaves out variants deleted from the catalog. Default false.
- `include_inventory` (boolean): true adds live Shopify inventory quantity, inventory policy and product tags to each row. Default false.
- `inventory` (string): Keep only variants with live inventory at zero or below, or above zero. Implies include_inventory. One of: `zero_or_below`, `positive`.
- `inventory_policy` (string): Keep only variants with this Shopify inventory policy; lowercase values are deprecated. Implies include_inventory. One of: `DENY`, `CONTINUE`, `deny`, `continue`.
- `page` (integer): Page number, starting at 1.
- `per_page` (integer): Rows per page, 1 to 250. Default 50.
- `search` (string): Matches product title, variant title and SKU.
- `product_status` (string): Comma-separated product statuses to keep, from active, draft, archived and unlisted.
- `product_tag` (string): Keep only variants whose product has this tag, case-insensitive. Implies include_inventory.
- `exclude_product_tag` (string): Leave out variants whose product has this tag, case-insensitive. Implies include_inventory.

## Returns

- `variants` (array of objects): Variants on this page. Absent with group_by=product.
  - `id` (string): ID of this variant's place on the offer.
  - `shopify_variant_id` (string): The variant, as gid://shopify/ProductVariant/&lt;id&gt;.
  - `product` (object): The variant's product.
    - `shopify_product_id` (string): The product, as gid://shopify/Product/&lt;id&gt;.
    - `title` (string): Product title.
    - `status` (string, nullable): Product status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.
    - `tags` (array of strings): The product's tags, read live from Shopify. Only with include_inventory or an inventory filter.
  - `title` (string): Variant name: product and variant title together, or the product title alone for a product's only variant.
  - `variant_title` (string): Variant title. Null for a product's only variant (Shopify's &quot;Default Title&quot;).
  - `sku` (string): Variant SKU. Null when it has none.
  - `discarded` (boolean): true when the variant has been deleted from the catalog.
  - `shipping_text` (string): This variant's own shipping text. Null when it has none and the offer's text shows.
  - `max_count` (integer): This variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.
  - `quantity_limit` (integer): The quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.
  - `preorder_count` (integer): Units preordered that count toward the quantity limit.
  - `quantity_limit_reached` (boolean): true when preorder_count has reached quantity_limit, or the batch limit on a batch offer.
  - `current_batch_id` (null): Batch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.
  - `created_at` (string): When the variant was added to the offer, ISO 8601 in UTC.
  - `batch_limits` (object): This variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.
  - `batch_ship_texts` (object): This variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.
  - `batch_progress` (null): Units sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.
  - `inventory_quantity` (integer): Live Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.
  - `inventory_policy` (string): Shopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops. One of: `CONTINUE`, `DENY`.
- `meta` (object): Pagination for the list.
  - `total_count` (integer): Items matching the filters, across all pages.
  - `page` (integer): Page returned, starting at 1.
  - `per_page` (integer): Most items per page.
  - `total_pages` (integer): Pages available at this per_page; 0 when nothing matches.
  - `total_products` (integer): Products matching the filters. Only with group_by=product.
  - `total_variants` (integer): Variants matching the filters. Only with group_by=product.
- `products` (array of objects): Products on this page with their variants on the offer. Only with group_by=product.
  - `shopify_product_id` (string): The product, as gid://shopify/Product/&lt;id&gt;.
  - `title` (string): Product title.
  - `image_url` (string): URL of the product's image. Null when it has none.
  - `variant_count` (integer): Variants of this product on this page.
  - `variants` (array of objects): This product's variants on the offer, as rows of the Products table.
    - `id` (string): ID of this variant's place on the offer.
    - `shopify_variant_id` (string): The variant, as gid://shopify/ProductVariant/&lt;id&gt;.
    - `product` (object): The variant's product.
      - `shopify_product_id` (string): The product, as gid://shopify/Product/&lt;id&gt;.
      - `title` (string): Product title.
      - `status` (string, nullable): Product status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.
      - `tags` (array of anys): The product's tags, read live from Shopify. Only with include_inventory or an inventory filter.
    - `title` (string): Variant name: product and variant title together, or the product title alone for a product's only variant.
    - `variant_title` (string): Variant title. Null for a product's only variant (Shopify's &quot;Default Title&quot;).
    - `sku` (string): Variant SKU. Null when it has none.
    - `discarded` (boolean): true when the variant has been deleted from the catalog.
    - `shipping_text` (string): This variant's own shipping text. Null when it has none and the offer's text shows.
    - `max_count` (integer): This variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.
    - `quantity_limit` (integer): The quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.
    - `preorder_count` (integer): Units preordered that count toward the quantity limit.
    - `quantity_limit_reached` (boolean): true when preorder_count has reached quantity_limit, or the batch limit on a batch offer.
    - `current_batch_id` (null): Batch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.
    - `created_at` (string): When the variant was added to the offer, ISO 8601 in UTC.
    - `batch_limits` (object): This variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.
    - `batch_ship_texts` (object): This variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.
    - `batch_progress` (null): Units sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.
    - `inventory_quantity` (integer): Live Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.
    - `inventory_policy` (string): Shopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops. One of: `CONTINUE`, `DENY`.
  - `status` (string): Product status in Shopify. Only with include_statuses=true.
- `inventory_included` (boolean): true when live Shopify inventory was read for this page; false when it could not be. Only with include_inventory or an inventory filter.
- `inventory_scope` (object): Which Shopify locations inventory_quantity counts. Only when inventory_included is true.
  - `locations` (string): all_locations, filtered_locations (the shop's preorder location filter), or unknown. One of: `all_locations`, `filtered_locations`, `unknown`.
  - `note` (string): Plain-sentence note on what inventory_quantity counts.
  - `location_count` (integer): Locations in the preorder location filter. Only with filtered_locations.
- `scanned` (integer): Rows read before the inventory, policy and tag filters were applied to the page.
- `unreadable` (integer): Of those, rows whose live inventory could not be read, so they were left out.
- `filter_error` (string): Why the filters were not applied and the page is empty. Only when live inventory could not be read.

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

## Examples

### List an offer's variants

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

### List an offer's variants filtered by sort, limit_reached and include_statuses

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants?sort=attached&limit_reached=5&include_statuses=false" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: example response shown.

```json
{
  "variants": [
    {
      "id": "b1f0c6d2-3e4a-4c1b-9a77-2d5e8f1a6c30",
      "shopify_variant_id": "gid://shopify/ProductVariant/44712349876501",
      "product": {
        "shopify_product_id": "gid://shopify/Product/8123456789013",
        "title": "Trail Runner Sneaker",
        "status": "active"
      },
      "title": "Trail Runner Sneaker",
      "variant_title": "US 9 / Black",
      "sku": "TRS-BLK-09",
      "discarded": false,
      "shipping_text": null,
      "max_count": 50,
      "quantity_limit": 50,
      "preorder_count": 18,
      "quantity_limit_reached": false,
      "current_batch_id": null,
      "created_at": "2026-06-25T10:42:10Z",
      "batch_limits": {},
      "batch_ship_texts": {},
      "batch_progress": null
    },
    {
      "id": "c94e2a17-5b6d-4f08-8e21-7a3c9d0b4f52",
      "shopify_variant_id": "gid://shopify/ProductVariant/44712349909269",
      "product": {
        "shopify_product_id": "gid://shopify/Product/8123456789013",
        "title": "Trail Runner Sneaker",
        "status": "active"
      },
      "title": "Trail Runner Sneaker",
      "variant_title": "US 10 / Black",
      "sku": "TRS-BLK-10",
      "discarded": false,
      "shipping_text": null,
      "max_count": 50,
      "quantity_limit": 50,
      "preorder_count": 50,
      "quantity_limit_reached": true,
      "current_batch_id": null,
      "created_at": "2026-06-25T10:42:10Z",
      "batch_limits": {},
      "batch_ship_texts": {},
      "batch_progress": null
    }
  ],
  "meta": {
    "total_count": 12,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}
```

## 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
    }
  ]
}
```

## 404

The resource does not exist for this shop, or the action path is not registered.

```json
{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "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
    }
  ]
}
```

