{"uid":"cap_KCZrYW7baN-jaO2RkbONn","slug":"forest-commerce-purchase-preflight-76231dfb","name":"Forest Commerce Purchase Preflight","description":"Machine-readable contract for active Forest paid capabilities. Unsigned paid calls return HTTP 402 with a PAYMENT-REQUIRED x402 challenge.","url":"https://http--forest-gas-station-mainnet--lcjl27p8lmjs.code.run/commerce/purchase-preflight?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"url":{"type":"string","pattern":"^https?://","maxLength":2048,"minLength":1,"description":"Public HTTP(S) URL to inspect, resolve, or compare."},"quantity":{"type":"integer","maximum":100,"minimum":1,"description":"Requested item quantity to validate against provider limits."},"variant_id":{"type":"string","maxLength":256,"minLength":1,"description":"Public provider variant identifier to validate."},"destination":{"type":"object","required":["country","postal_code"],"properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Public country value used to scope this lookup."},"postal_code":{"type":"string","maxLength":32,"minLength":1,"description":"Public postal code value used to scope this lookup."}},"description":"Delivery country and postal code used to quote delivery availability.","additionalProperties":false}}},"responseSchema":{"type":"json","example":{"ok":true,"data":{"scope":"anonymous_bounded_preflight_not_purchase_guarantee","state":"ready","blockers":[],"currency":"example","platform":"example","subtotal":1,"item_price":1,"deliverable":false,"checkout_url":"example","canonical_url":"example","cart_possible":false,"session_scope":"request_scoped_ephemeral","delivery_checked":false,"shipping_options":[],"accepted_quantity":1,"cheapest_shipping":{"name":"example","price":1,"currency":"example","max_delivery_date":"example","min_delivery_date":"example"},"checkout_possible":false,"order_not_created":true,"delivery_requested":false,"requested_quantity":1,"selected_variant_id":"example","payment_not_attempted":true,"shipping_option_count":0,"provider_request_count":0,"customer_session_touched":false},"meta":{"cache":"miss","provider":"shopify-ajax","checked_at":"2026-01-01T00:00:00.000Z","duration_ms":0},"version":"1","capability":"commerce.purchase-preflight"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.006","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.006/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.006","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.006","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_ly65DxV4NX3hZs1qKa8Rk","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.006","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Validates whether a specific product variant can be purchased and shipped to a destination, returning price, availability, and shipping options before committing to a transaction.","exampleAgentPrompt":"Before I buy 2 units of the blue variant (variant ID 'gid://shopify/ProductVariant/123456') from https://example-shop.com/products/widget, check if it can actually be delivered to postal code 10001 in the US and what shipping will cost.","exampleUseCases":[{"title":"Pre-purchase shipping validation","prompt":"Can you check if I can order 3 of variant 'SKU-ABC-789' from https://store.example.com/products/backpack and get it shipped to postal code 90210 in the US — and what are the shipping options?"},{"title":"Availability check before gifting","prompt":"I want to send a gift to someone in Canada, postal code M5H 2N2 — can you verify that variant 'variant-red-large' at https://gifts.example.com/products/candle is actually available and shippable there, and what it would cost?"},{"title":"Agent cart validation before checkout","prompt":"Before trying to add it to cart, check whether 1 unit of variant 'prod_987xyz' from https://boutique.example.com/products/dress can be purchased and shipped to 33101 in the US, and tell me if there are any blockers."}],"resultDescription":"Returns a structured preflight object indicating whether the product is available (state: ready/blocked), a list of blockers if any, item price, subtotal, accepted quantity, available shipping options with names/prices/delivery dates, cheapest shipping option, whether delivery is possible to the given destination, and a checkout URL if a cart is possible. Also includes metadata about provider (e.g. shopify-ajax), cache status, and response duration.","failureModes":["Invalid or unreachable product URL returns error or blockers in response","Variant ID not found at the provider results in blockers or unavailable state","Destination country/postal code unsupported for shipping returns deliverable: false","Quantity exceeds provider limit (max 100) returns validation error","Missing required fields (url, country, postal_code) returns 400 Bad Request","Unsigned payment call returns HTTP 402 with x402 PAYMENT-REQUIRED challenge","Provider (Shopify) timeout or rate limit may cause elevated duration_ms or error"],"whenToPreferThis":"Use this endpoint when you need to validate purchase feasibility for a specific product variant before attempting checkout — especially when you need to confirm shipping availability to a specific country/postal code, check quantity limits, identify blockers, and surface shipping cost options. Prefer this over scraping a product page when you need structured, machine-readable preflight data including checkout URLs and shipping quotes. Best suited for Shopify-backed storefronts.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-22T18:31:01.218Z","isFirstParty":false,"canonicalSlug":"forest-commerce-purchase-preflight-76231dfb"}