Skip to content

List an offer's variants

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

GET/preorders/offers/{id}/products/variants

Costs 1 rate-limit point · Rate limits

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

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 < meta.total_pages.

Also searched aslist variants on offervariants attached to offershow offer variantsattached variantsoffer variant listlist products on offersearch offer products

Path parameters

Query parameters

  • sortstring

    Sort order. Default attached (the order variants were added); title is the same as title_asc.

    One of attachedtitletitle_asctitle_desccreated_asccreated_descadded_ascadded_descsold_ascsold_desc
  • limit_reachedboolean

    true keeps only variants that have reached their quantity limit.

  • include_statusesboolean

    true reads product statuses not stored yet from Shopify. Default false.

    Default false
  • group_bystring

    product returns products with their variants and pages by product instead of by variant.

    One of product
  • exclude_discardedboolean

    true leaves out variants deleted from the catalog. Default false.

    Default false
  • include_inventoryboolean

    true adds live Shopify inventory quantity, inventory policy and product tags to each row. Default false.

    Default false
  • inventorystring

    Keep only variants with live inventory at zero or below, or above zero. Implies include_inventory.

    One of zero_or_belowpositive
  • inventory_policystring

    Keep only variants with this Shopify inventory policy; lowercase values are deprecated. Implies include_inventory.

    One of DENYCONTINUEdenycontinue
  • pageinteger

    Page number, starting at 1.

    Default 1
  • per_pageinteger

    Rows per page, 1 to 250. Default 50.

    Default 50
  • searchstring

    Matches product title, variant title and SKU.

  • product_statusstring

    Comma-separated product statuses to keep, from active, draft, archived and unlisted.

  • product_tagstring

    Keep only variants whose product has this tag, case-insensitive. Implies include_inventory.

  • exclude_product_tagstring

    Leave out variants whose product has this tag, case-insensitive. Implies include_inventory.

Returns

  • variantsarray of objects

    Variants on this page. Absent with group_by=product.

    Show 19 child attributesHide child attributes
    • idstring

      ID of this variant's place on the offer.

    • shopify_variant_idstring

      The variant, as gid://shopify/ProductVariant/<id>.

    • productobject

      The variant's product.

      Show 4 child attributesHide child attributes
      • shopify_product_idstring

        The product, as gid://shopify/Product/<id>.

      • titlestring

        Product title.

      • statusstring, nullable

        Product status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.

      • tagsarray of strings

        The product's tags, read live from Shopify. Only with include_inventory or an inventory filter.

    • titlestring

      Variant name: product and variant title together, or the product title alone for a product's only variant.

    • variant_titlestring

      Variant title. Null for a product's only variant (Shopify's "Default Title").

    • skustring

      Variant SKU. Null when it has none.

    • discardedboolean

      true when the variant has been deleted from the catalog.

    • shipping_textstring

      This variant's own shipping text. Null when it has none and the offer's text shows.

    • max_countinteger

      This variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.

    • quantity_limitinteger

      The quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.

    • preorder_countinteger

      Units preordered that count toward the quantity limit.

    • quantity_limit_reachedboolean

      true when preorder_count has reached quantity_limit, or the batch limit on a batch offer.

    • current_batch_idnull

      Batch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.

    • created_atstring

      When the variant was added to the offer, ISO 8601 in UTC.

    • batch_limitsobject

      This variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.

    • batch_ship_textsobject

      This variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.

    • batch_progressnull

      Units sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.

    • inventory_quantityinteger

      Live Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.

    • inventory_policystring

      Shopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops.

      One of CONTINUEDENY
  • metaobject

    Pagination for the list.

    Show 6 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.

    • total_productsinteger

      Products matching the filters. Only with group_by=product.

    • total_variantsinteger

      Variants matching the filters. Only with group_by=product.

  • productsarray of objects

    Products on this page with their variants on the offer. Only with group_by=product.

    Show 6 child attributesHide child attributes
    • shopify_product_idstring

      The product, as gid://shopify/Product/<id>.

    • titlestring

      Product title.

    • image_urlstring

      URL of the product's image. Null when it has none.

    • variant_countinteger

      Variants of this product on this page.

    • variantsarray of objects

      This product's variants on the offer, as rows of the Products table.

      Show 19 child attributesHide child attributes
      • idstring

        ID of this variant's place on the offer.

      • shopify_variant_idstring

        The variant, as gid://shopify/ProductVariant/<id>.

      • productobject

        The variant's product.

        Show 4 child attributesHide child attributes
        • shopify_product_idstring

          The product, as gid://shopify/Product/<id>.

        • titlestring

          Product title.

        • statusstring, nullable

          Product status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.

        • tagsarray of anys

          The product's tags, read live from Shopify. Only with include_inventory or an inventory filter.

      • titlestring

        Variant name: product and variant title together, or the product title alone for a product's only variant.

      • variant_titlestring

        Variant title. Null for a product's only variant (Shopify's "Default Title").

      • skustring

        Variant SKU. Null when it has none.

      • discardedboolean

        true when the variant has been deleted from the catalog.

      • shipping_textstring

        This variant's own shipping text. Null when it has none and the offer's text shows.

      • max_countinteger

        This variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.

      • quantity_limitinteger

        The quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.

      • preorder_countinteger

        Units preordered that count toward the quantity limit.

      • quantity_limit_reachedboolean

        true when preorder_count has reached quantity_limit, or the batch limit on a batch offer.

      • current_batch_idnull

        Batch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.

      • created_atstring

        When the variant was added to the offer, ISO 8601 in UTC.

      • batch_limitsobject

        This variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.

      • batch_ship_textsobject

        This variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.

      • batch_progressnull

        Units sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.

      • inventory_quantityinteger

        Live Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.

      • inventory_policystring

        Shopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops.

        One of CONTINUEDENY
    • statusstring

      Product status in Shopify. Only with include_statuses=true.

  • inventory_includedboolean

    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_scopeobject

    Which Shopify locations inventory_quantity counts. Only when inventory_included is true.

    Show 3 child attributesHide child attributes
    • locationsstring

      all_locations, filtered_locations (the shop's preorder location filter), or unknown.

      One of all_locationsfiltered_locationsunknown
    • notestring

      Plain-sentence note on what inventory_quantity counts.

    • location_countinteger

      Locations in the preorder location filter. Only with filtered_locations.

  • scannedinteger

    Rows read before the inventory, policy and tag filters were applied to the page.

  • unreadableinteger

    Of those, rows whose live inventory could not be read, so they were left out.

  • filter_errorstring

    Why the filters were not applied and the page is empty. Only when live inventory could not be read.

Errors

404
not_found

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

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.

GET/preorders/offers/{id}/products/variants
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "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
  }
}