Skip to content

Check variant availability

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

GET/preorders/product_variants/availability

Costs 1 rate-limit point · Rate limits

Resolve which preorder offer applies to Shopify variants for a buyer country, with its stock condition and schedule. Beta.

country is the buyer's ISO 3166-1 alpha-2 country. status live means an offer applies and its limit is not reached, sold_out that its limit is reached; the caller still checks live inventory per stock_condition (in_stock: quantity above 0; out_of_stock: 0 or below with continue selling; any_stock_level: either). Unknown or deleted variants are not_enrolled; malformed ids are listed in errors. include[]=offer_details adds the offer's shipping_text, max_count, quantity_limit, preorder_count and quantity_limit_reached to preorder, as GET /preorders/products lists them; shipping_text is the text the buyer sees.

Also searched asvariant availabilityis variant on preorderpreorder availability by countryresolve preorder for country

Query parameters

  • countrystringRequired

    Buyer's country as an ISO 3166-1 alpha-2 code, such as US.

  • shopify_variant_idsstring

    Comma-separated variants to check, up to 100, as numeric IDs or gid://shopify/ProductVariant/<id>; an array also works.

  • includestring

    Extra detail to add; offer_details adds the offer's shipping text and quantity limits. Comma-separated or an array.

Returns

  • countrystring
    Example: US
  • product_variantsarray of objects
    Show 4 child attributesHide child attributes
    • shopify_variant_idstring
      Example: gid://shopify/ProductVariant/47284734423096
    • statusstring
      Example: live
    • stock_conditionstring, nullable
      Example: out_of_stock
    • preorderobject, nullable
      Show 7 child attributesHide child attributes
      • idstring
        Example: 73a74948-2b57-4cc3-971f-2b441828c977
      • scheduleobject
        Show 2 child attributesHide child attributes
        • start_datestring, nullable
        • end_datestring, nullable
      • shipping_textstring, nullable
      • max_countinteger, nullable
      • quantity_limitinteger, nullable
      • preorder_countinteger
      • quantity_limit_reachedboolean
  • errorsarray of objects
    Show 2 child attributesHide child attributes
    • shopify_variant_idstring
    • errorstring

Errors

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The action refused the request for a reason that is not a single bad field.

503
upstream_unavailable

A service the answer depends on did not respond in time.

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/product_variants/availability
curl "https://app.stoqapp.com/api/v2/external/preorders/product_variants/availability?country=US" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "country": "US",
  "product_variants": [
    {
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
      "status": "live",
      "stock_condition": "out_of_stock",
      "preorder": {
        "id": "73a74948-2b57-4cc3-971f-2b441828c977",
        "schedule": {
          "start_date": null,
          "end_date": null
        }
      }
    },
    {
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734521400",
      "status": "not_enrolled",
      "stock_condition": null,
      "preorder": null
    }
  ],
  "errors": []
}