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.

When to use it

• Diagnose a Shopify /cart/add.js 422 response when a variant appears in stock.
• Verify that a newly created variant has propagated to the customer-facing cart before releasing it.
• Run pre-launch QA after inventory, fulfillment-location, theme, app, bundle, or catalog changes.
• Confirm that the exact requested quantity and expected price reach the observable storefront path.

This is a transaction-path check for Shopify developers, agencies, QA teams, and automation operators. It is not a catalog scraper or a substitute for Shopify Admin inventory data.

Pricing

The Actor costs $0.005 per result row through Apify pay-per-event billing. Platform usage is included.

• 1 check producing 1 row: $0.005
• 10 checks producing 10 rows: $0.05
• Maximum 50-check batch producing 50 rows: $0.25

Each completed classification is one billable result, including an input_error row inside a batch. The Actor checks the remaining run charge limit before starting each item and stops before doing work that cannot produce a paid result. Input rejected by Apify's top-level schema before an Actor run does not produce a result row.

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 and is limited to 1–1000. Option-name resolution and GraphQL GIDs are not supported in v0; pass the numeric Shopify variant ID. expectedCurrency, when supplied, must be a three-letter ISO code such as USD.

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 over public network destinations. It blocks local, private, link-local, network-metadata, and non-standard-port destinations, including redirect targets. It does not authenticate, bypass CAPTCHA, enter customer information, enter shipping information, submit payment, reserve inventory intentionally, or place orders.

Some storefronts use protection, custom cart implementations, selling plans, or market/location rules that cannot be resolved from a public check. Those cases return unsupported_storefront or inconclusive rather than claiming a definitive result.

Support

For product questions or a reproducible incorrect classification, contact hello@silverrooklabs.com. Include only the public product URL, variant ID, requested quantity, Actor run ID, and observed status. Do not send Shopify credentials, customer data, session cookies, or private store information.

Commands

npm test
npm run build
npm start