Check Live Variant Stock, Product Details & Sizing
products.items.check_stockVerify real-time live stock availability, discounted pricing, product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care Instructions), shipping/return policies, and available size variants for a specific fashion product handle.
PURPOSE & DISAMBIGUATION:
Real-time inventory and metadata inspection tool for a single product.
Computes the full size-availability matrix, active pricing, discount percentage, specifications dictionary, and resolves the 1-click checkout permalink for a chosen size.
Distinct from 'products.items.get_by_handle': Use this tool to check live stock, available sizes, formatted policies, and get size-specific checkout links; use 'products.items.get_by_handle' for raw catalog document retrieval.
Distinct from 'checkout.links.get_direct_url': Use this tool to verify stock and sizing options; use 'checkout.links.get_direct_url' to generate a final permalink once a size is confirmed.
WHEN TO USE:
Before presenting or confirming a product to the user, to verify whether their desired size is in-stock.
When generating the mandatory product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
When checking return/exchange eligibility and shipping dispatch timelines.
WHEN NOT TO USE:
Do NOT use to search across multiple catalog products (use 'products.search.text' or 'products.search.image_url').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Automatically maps numeric and Indian/UK/EU shoe and apparel sizes (e.g. '6' -> EU 39, 'M' -> Medium).
Formats negative return days cleanly as 'Exchange only |X| days' (e.g. -7 -> 'Exchange only 7 days').
Returns structured JSON with 'is_in_stock', 'available_sizes', 'out_of_stock_sizes', 'product_details', 'shipping_policy_text', and 'return_policy_text'.
PARAMETERS & CONSTRAINTS:
'handle' (string, required): Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206').
'desired_size' (string, optional): Size label to verify against the variant inventory (e.g. 'M', 'L', 'XL', '32', '40').
'size_index' (integer >= 0, optional): Zero-based index of the size variant.
MANDATORY AGENT INSTRUCTIONS:
Always inform the user of available in-stock sizes, fast dispatch SLA, and return policy (Negative return days = 'Exchange only |X| days').
Display the product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
Return the base link (https://s.polopan.com/p/{handle}) during browsing. Provide direct checkout link (https://s.polopan.com/p/{handle}/{size_index}) ONLY after the user's size is finalized.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206') | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| size_index | No | Zero-based index of the specific size variant to inspect | |
| desired_size | No | Optional size query to verify against variant inventory (e.g. 'M', 'L', 'XL', '32', '40') |