---
title: "Recalculate a variant's count"
description: "Recompute preorder_count for a variant from active order line items, then push to Shopify."
url: https://docs.stoqapp.com/v2-reference/preorders-product-variants/recalculate-a-variants-count/
api: "API v2 reference"
method: POST
path: "/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count"
---

# Recalculate a variant's count

`POST https://app.stoqapp.com/api/v2/external/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count`

Recompute preorder_count for a variant from active order line items, then push to Shopify.

**Note:** Use it when a variant's preorder_count no longer matches its orders, so the storefront hits the limit too early or too late. For each offer the variant is in, STOQ adds up the units on its preorder orders, leaving out cancelled units and orders retired by POST .../reset_preorder_count, saves that count and writes the live offer's count to Shopify. Safe to repeat. Returns 202 with the variant as [`GET /preorders/product_variants/:shopify_variant_id`](https://docs.stoqapp.com/v2-reference/preorders-product-variants/get-a-variant/) shows it; 404 `not_found` when STOQ has no such variant. For many variants use [`POST /preorders/product_variants/bulk_recalculate_preorder_counts`](https://docs.stoqapp.com/v2-reference/preorders-product-variants/bulk-recalculate-counts/).

## Path parameters

- `shopify_variant_id` (string, required): The variant, as gid://shopify/ProductVariant/&lt;id&gt; or the numeric ID.

## Headers

- `Idempotency-Key` (string): A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with `Idempotent-Replayed: true`, without running again; the same key with a different method, path or body is refused (422 `idempotency_key_reused`); a retry while the first is still running gets 409 `idempotency_key_in_progress`. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

## Returns

- `variant` (object)
  - `id` (string): e.g. `3f9a6c1e-8b2d-4e57-a0c4-6d1e9b7f2a85`
  - `shopify_variant_id` (string): e.g. `gid://shopify/ProductVariant/47284734423096`
  - `product` (object)
    - `shopify_product_id` (string): e.g. `gid://shopify/Product/8784906035384`
    - `title` (string): e.g. `Classic Sneaker`
    - `status` (null): e.g. `active`
  - `variant_title` (string): e.g. `Blue / Medium`
  - `sku` (string): e.g. `CS-BLU-M`
  - `image_url` (string): e.g. `https://cdn.shopify.com/s/files/1/0712/3456/7890/files/cl…`
  - `offers` (array of objects)
    - `id` (string): e.g. `73a74948-2b57-4cc3-971f-2b441828c977`
    - `shipping_text` (string): e.g. `Ships in early August`
    - `max_count` (integer): e.g. `100`
    - `quantity_limit` (integer): e.g. `100`
    - `preorder_count` (integer): e.g. `38`
    - `quantity_limit_reached` (boolean): e.g. `false`
  - `preorder_units_sold` (integer): e.g. `41`
  - `line_item_revenue` (string): e.g. `4510.00`
- `offers` (array of objects)
  - `id` (string): e.g. `73a74948-2b57-4cc3-971f-2b441828c977`
  - `internal_name` (string): e.g. `summer-2026`
  - `current_status` (string): e.g. `live`
  - `inventory` (object)
    - `stock_condition` (string): e.g. `out_of_stock`
  - `markets` (object)
    - `scope` (string): e.g. `all`
  - `shipping` (object)
    - `timeline` (object)
      - `scope` (string): e.g. `per_variant`
  - `widget` (object)
    - `disclaimer` (object)
      - `disclaimer_text` (string): e.g. `Ships in August. You're charged today.`
  - `payments` (object)
    - `options_offered` (string): e.g. `full`

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

## Example request

```sh
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 202

Success: example response shown.

```json
{
  "variant": {
    "id": "3f9a6c1e-8b2d-4e57-a0c4-6d1e9b7f2a85",
    "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
    "product": {
      "shopify_product_id": "gid://shopify/Product/8784906035384",
      "title": "Classic Sneaker",
      "status": "active"
    },
    "variant_title": "Blue / Medium",
    "sku": "CS-BLU-M",
    "image_url": "https://cdn.shopify.com/s/files/1/0712/3456/7890/files/classic-sneaker-blue.jpg",
    "offers": [
      {
        "id": "73a74948-2b57-4cc3-971f-2b441828c977",
        "shipping_text": "Ships in early August",
        "max_count": 100,
        "quantity_limit": 100,
        "preorder_count": 38,
        "quantity_limit_reached": false
      }
    ],
    "preorder_units_sold": 41,
    "line_item_revenue": "4510.00"
  },
  "offers": [
    {
      "id": "73a74948-2b57-4cc3-971f-2b441828c977",
      "internal_name": "summer-2026",
      "current_status": "live",
      "inventory": {
        "stock_condition": "out_of_stock"
      },
      "markets": {
        "scope": "all"
      },
      "shipping": {
        "timeline": {
          "scope": "per_variant"
        }
      },
      "widget": {
        "disclaimer": {
          "disclaimer_text": "Ships in August. You're charged today."
        }
      },
      "payments": {
        "options_offered": "full"
      }
    }
  ]
}
```

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

## 409

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

```json
{
  "errors": [
    "A request with this Idempotency-Key is still running"
  ],
  "code": "idempotency_key_in_progress",
  "details": [
    {
      "code": "idempotency_key_in_progress",
      "message": "A request with this Idempotency-Key is still running",
      "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
    }
  ]
}
```

