Shopify Variant Cartability Checker

Verify whether an exact Shopify product variant and quantity can actually enter cart and reach checkout right now.

Shopify catalog availability does not always reflect transactional reality. This Actor checks the exact variant against the live public storefront cart flow and returns a deterministic verdict.

The core checkCartability() function is independent of Apify; src/main.ts is only the Actor wrapper.

Input

{
  "productUrl": "https://store.example/products/example-product",
  "variantId": "1234567890",
  "quantity": 1,
  "expectedPrice": 49.99,
  "expectedCurrency": "USD"
}

productUrl and variantId are required. quantity defaults to 1. Option-name resolution is not supported in v0; pass the exact Shopify variant ID.

Batch input is also supported. The Actor emits one dataset row per check:

{
  "checks": [
    {
      "productUrl": "https://store.example/products/example-product",
      "variantId": "1234567890",
      "quantity": 1
    },
    {
      "productUrl": "https://store.example/products/example-product",
      "variantId": "9876543210",
      "quantity": 2,
      "expectedPrice": 39.99,
      "expectedCurrency": "USD"
    }
  ]
}

Single-check input remains supported for backward compatibility. Batch runs accept up to 50 checks. If one batch item has invalid input, that item returns an input_error row and the remaining checks continue.

Output

{
  "status": "cartable",
  "productUrl": "https://store.example/products/example-product",
  "storeOrigin": "https://store.example",
  "variantId": "1234567890",
  "variantFound": true,
  "declaredAvailable": false,
  "requestedQuantity": 1,
  "acceptedQuantity": 1,
  "observedPrice": 49.99,
  "observedPriceMinor": 4999,
  "currency": "USD",
  "addToCartAccepted": true,
  "cartLineMatched": true,
  "checkoutReachable": true,
  "expectedPrice": 49.99,
  "expectedCurrency": "USD",
  "priceMatchesExpected": true,
  "checkedAt": "2026-08-15T16:00:00.000Z"
}

declaredAvailable is catalog metadata. status is based on the observed transactional flow. They may legitimately disagree.

Statuses

Status	Meaning
cartable	Exact variant exists, requested quantity appears in cart, exact cart line matches, and checkout is reachable.
variant_not_found	Product metadata was accessible, but the supplied variant was absent.
unavailable	Transactional evidence shows quantity 1 cannot be placed into cart because of availability.
quantity_rejected	Exact variant exists, but the cart accepts fewer than requested.
cart_rejected	The cart mutation gives a definitive rejection.
checkout_unreachable	The exact line enters cart, but checkout cannot be reached through ordinary public behavior.
unsupported_storefront	The supplied page does not expose the standard Shopify flow this Actor supports.
inconclusive	Network, protection, or response behavior is ambiguous.
input_error	Batch item input is invalid. Other batch items still run.

Price mismatch is not a terminal state. If expectedPrice or expectedCurrency differs from the observed result, the Actor reports the transactional status and sets priceMatchesExpected to false with a reason code where available.

Boundaries

This Actor only checks public storefront behavior. It does not authenticate, bypass CAPTCHA, enter customer information, enter shipping information, submit payment, reserve inventory intentionally, or place orders.

Commands

npm test
npm run build
npm start