llms.txt
Compare with other sites' llms.txt files →# unhuman shopping
Hello, agent. You found the everything store.
Buy products from Amazon, Walmart, Nordstrom, Gap, Old Navy, Banana Republic, Athleta, Zara, Quince, Birkenstock, Net-a-Porter, Moda Operandi, Loro Piana, On, Shopbop, SSENSE, Club Monaco, Rag & Bone, J.Crew, Mr Porter, Vince, Theory, Vuori, H&M, Saks Fifth Avenue, Neiman Marcus, Levi's, Toteme, and any Shopify-powered store via API, paid with Bitcoin Lightning (L402). Search first, quote each item, then place one same-retailer purchase (exception: gap, oldnavy, and bananarepublic share one Gap Inc. cart and may mix in a single purchase; athleta does not share that cart and orders separately). Nordstrom, Gap-family, Athleta, Zara, Quince, Birkenstock, Net-a-Porter, Moda Operandi, Loro Piana, On, Shopbop, SSENSE, Club Monaco, Rag & Bone, J.Crew, Mr Porter, Vince, Theory, Vuori, H&M, Saks Fifth Avenue, Neiman Marcus, Levi's, and Toteme quotes are verified against live retailer pricing before checkout, and orders are placed with the selected product URL. retailer=shopify searches every Shopify merchant at once; each result's retailer is that merchant's own storefront domain, and its quote is an estimated total (the listing price plus a buffer standing in for shipping/tax, requires zip) — any unused buffer is refunded to your refund_destination after the order. Already have a Shopify product-page URL (…/products/{handle})? Pass it as q with retailer={store domain} (or retailer=shopify) and the catalog performs an exact lookup of that product instead of a keyword search — use this whenever a store's item does not surface in search results.
> **US only.** Shipping is limited to addresses within the United States.
## Recommended Workflow
1. Search for products → GET /api/catalog?q={query}&retailer={retailer}&zip={zip} (free)
2. Pick one or more products from the same retailer — note each product_id, retailer, and quote_url
3. Need more product photos without a quote → GET /api/catalog/images?url={product_url} (free, optional)
4. Get an exact quote for each product line → GET /api/catalog/{productId}?retailer={retailer}&zip={zip} (free). Shopify-merchant and cross-retailer results (bestbuy, homedepot, ...) are quoted by following the search result's quote_url instead — GET /api/catalog/quote (free; see Quote by URL). A Shopify line can optionally be upgraded to an address-exact total → POST /api/catalog/quote (free; see Exact Shopify Quote)
5. Preview the whole basket's real total → POST /api/order/preview with all the quote_tokens (free, read-only; returns the single order-level service fee plus buffer-inclusive totals). Show the response's charge_amount_cents as the price before charging — do not sum per-line fees yourself.
6. Place the order → POST /api/order with each distinct line's quote_token, a quantity (integer 1-100; use one line per distinct product), and shipping address. Split the purchase by retailer when retailers differ.
## Endpoints
Base URL: https://unhuman.shopping
### Search Products (FREE)
GET /api/catalog?q={query}&retailer={retailer}&zip={zip}&page={page}
Search supported retailers for products. Free — no payment required.
This endpoint is optimized for cheap discovery, not final checkout pricing,
even when q already names a specific product ID.
Query parameters:
- q (required): Search query or retailer product ID (e.g. "wireless earbuds", "B0CX23V2ZK", "2101922242", "n4RTalM")
- retailer (optional): Scope to search. Default: "amazon". Supported values:
- "all": Federated search across the cross-retailer allowlist stores (Amazon, Walmart, Best Buy, ...), every Shopify merchant, and every first-class fashion retailer below (one federated fashion search over all of them; ranking decides which stores fill its rows, so scope to a retailer directly to see its full assortment) in parallel. Each result carries its real retailer. Slow/failing sources degrade to partial results (see sources in the response)
- "amazon", "walmart", "nordstrom", "gap", "oldnavy", "bananarepublic", "athleta", "zara", "quince", "birkenstock", "netaporter", "modaoperandi", "loropiana", "on", "shopbop", "ssense", "clubmonaco", "ragandbone", "jcrew", "mrporter", "vince", "theory", "vuori", "hm", "saks", "neimanmarcus", "levis", "toteme": One first-class retailer (Shopbop also carries the former East Dane menswear assortment; eastdane.com now redirects to Shopbop)
- "shopify": Every Shopify merchant's storefront at once; each result carries the merchant's own domain as its retailer (e.g. "flightcoffeeco.com")
- A merchant domain (any value containing a dot, e.g. "flightcoffeeco.com"): Just that Shopify merchant's products
- An allowlist merchant name ("bestbuy", "homedepot", "lowes", "costco", "wayfair", "macys", "kohls", "staples"): That store via cross-retailer search
- zip (optional): Delivery ZIP code used when building quote_url
- page (optional): Result page (default 1)
- page_token (optional): Opaque pagination token for fashion-retailer (nordstrom/gap/oldnavy/bananarepublic/athleta/zara/quince/birkenstock/netaporter/modaoperandi/loropiana/on/shopbop/ssense/clubmonaco/ragandbone/jcrew/mrporter/vince/theory/vuori/hm/saks/neimanmarcus/levis/toteme) and Shopify searches
- sources (optional, retailer=all only): Comma-separated subset of the federated scopes to fan out to — "supported_retailers", "shopify_merchants", "nordstrom". Default: all three
Filter parameters (optional; Shopify's vocabulary): filters are passed through ONLY to sources that support them natively and are dropped for the rest — a dropped filter means that source's results are unconstrained on that dimension (reported in sources[].dropped_filters on retailer=all). Shopify honors the supported vocabulary; the fashion retailers (nordstrom/gap/oldnavy/bananarepublic/athleta/zara/quince/birkenstock/netaporter/modaoperandi/loropiana/on/shopbop/ssense/clubmonaco/ragandbone/jcrew/mrporter/vince/theory/vuori/hm/saks/neimanmarcus/levis/toteme) honor price and available=true; Amazon/Walmart/cross-retailer honor none.
- price_min / price_max: Price bounds in integer cents
- available: "true" for quoteable in-stock results. available=false is not supported and returns 400
- ships_to: ISO 3166-1 country code (e.g. "US")
Response: JSON object containing:
- products: Array of products, each with:
- asin: Amazon ASIN when retailer is "amazon"
- product_id: Retailer product ID
- retailer: Retailer name
- title: Product name
- retailer_price_cents: Retailer product price in cents, or null when unverified
- amazon_price_cents: Amazon product price in cents (included for backward compatibility), or null when unverified
- unverified_retailer_price_cents: Unverified retailer price in cents for fashion-retailer results
- price_status: "verified" or "unverified"
- shipping_estimate_cents: Shipping estimate when already known, otherwise null
- total_cents: Product + shipping when shipping is already known, otherwise null
- service_fee_cents: Service fee when total_cents is known, otherwise null
- estimated_checkout_total_cents: All-in checkout estimate (goods + service fee + order-processing fees) when enough pricing data is available, otherwise null. This is the ONE price to show the customer — identical for Lightning and card for buffered quotes (an exact Shopify quote later supersedes it and charges Lightning less; see Exact Shopify Quote); when null (shipping/tax unknown until the quote), show the product price instead — retailer_price_cents when present, otherwise unverified_retailer_price_cents — and get the all-in number from the quote
- currency: "USD"
- product_url: Retailer product URL
- url: Retailer product URL
- thumbnail: Product image URL
- images: Array of product image URLs (primary image first; may be empty). Search results usually carry one image — the full gallery comes from the quote response
- rating: Star rating when available
- is_prime: Always null in search results — Prime eligibility is unknown until the quote response resolves it
- quote_required: Always true for search results
- quote_available: Whether quote_url can be called for exact checkout pricing
- brand: Store/brand name when known (Shopify results carry the merchant's store name)
- details: Short merchant-authored product detail (materials, specs) when available
- quote_url: Call this next to get one quote_token for that chosen product line. Follow it verbatim — for Shopify-merchant and cross-retailer results it points at GET /api/catalog/quote, and Shopify quote_urls are signed capabilities that cannot be reconstructed by hand. For Shopify-merchant results the quote is an estimated total: the listing price plus a buffer standing in for shipping/tax (requires zip); any unused buffer is refunded to your refund_destination after the order
- query: The search query
- page: Current page number
- next_page_token: Opaque pagination token for the next fashion-retailer page, when available
- retailer: The scope searched
- sources (retailer=all only): Per-store-scope diagnostics — { source, status: "ok"|"timeout"|"error", count, dropped_filters }. source is one of "supported_retailers", "shopify_merchants", or "nordstrom". A non-ok source means its stores are missing from this result set, not that no products exist there
Example:
GET /api/catalog?q=wireless+earbuds&retailer=walmart&zip=30312
GET /api/catalog?q=dress&retailer=nordstrom&zip=30312
### Product Images (FREE)
GET /api/catalog/images?url={productUrl}
Get the full image gallery and basic metadata for a retailer product URL (e.g. the product_url from a search result) without minting a quote. Amazon and Walmart galleries come from retailer product data; other domains come from a third-party product index. Prices are unverified — use quote_url for checkout pricing. The first request for a product may take a few seconds; repeat requests are fast.
Most useful for amazon and walmart search results, which usually carry one image. Fashion-retailer search results already include their gallery in the images field.
Query parameters:
- url (required): Percent-encoded retailer product URL
Response: JSON object containing:
- product:
- title: Product name
- url: The requested retailer product URL
- thumbnail: Primary product image URL, when available
- images: Array of product image URLs (primary image first; may be empty)
- unverified_price_cents: Unverified product price in cents, when available
- currency: Price currency, when a price is present
- retailer_domain: Registrable retailer domain of the requested URL (e.g. "amazon.com")
Returns 404 when the product index resolves a non-amazon/walmart URL to a product sold on a different retailer's domain, and 400 when url is missing or not a valid URL.
Example:
GET /api/catalog/images?url=https%3A%2F%2Fwww.amazon.com%2Fdp%2FB0CX23V2ZK
### Quote One Product (FREE)
GET /api/catalog/{productId}?retailer={retailer}&zip={zip}
Get exact checkout pricing and a quote_token for one chosen Amazon, Walmart, Nordstrom, Gap, Old Navy, Banana Republic, Athleta, Zara, Quince, Birkenstock, Net-a-Porter, Moda Operandi, Loro Piana, On, Shopbop, SSENSE, Club Monaco, Rag & Bone, J.Crew, Mr Porter, Vince, Theory, Vuori, H&M, Saks Fifth Avenue, Neiman Marcus, Levi's, or Toteme product line. Fashion-retailer quotes price the selected variant from the retailer's live product page, read at most 15 minutes before the quote_token is minted. Their shipping and tax are one refundable estimate in estimate_buffer_cents (20% of the item price, at least $8) rather than a shipping line; any unused portion is refunded after the order.
Query parameters:
- retailer (optional): Retailer to quote. Supported values: "amazon", "walmart", "nordstrom", "gap", "oldnavy", "bananarepublic", "athleta", "zara", "quince", "birkenstock", "netaporter", "modaoperandi", "loropiana", "on", "shopbop", "ssense", "clubmonaco", "ragandbone", "jcrew", "mrporter", "vince", "theory", "vuori", "hm", "saks", "neimanmarcus", "levis", "toteme". Default: "amazon"
- zip (optional): Delivery ZIP code to associate with the quote
Response: JSON object containing:
- product:
- asin: Amazon product ID when retailer is "amazon"
- product_id: Retailer product ID
- retailer: Retailer name
- title: Product name
- retailer_price_cents: Retailer product price in cents
- amazon_price_cents: Amazon product price in cents (included for backward compatibility)
- shipping_estimate_cents: Real shipping estimate in cents (actual carrier/retailer shipping only; the tax + not-yet-final-shipping headroom is the separate estimate_buffer_cents field, NOT folded in here); null for fashion-retailer quotes, whose shipping is inside estimate_buffer_cents
- estimate_buffer_cents: Refundable upfront estimate for tax and shipping that isn't final yet, added on top of shipping. Charged now and reconciled by a refund after the retailer confirms the final cost
- delivery_days: Selected shipping option delivery range as { min, max } when available
- delivery_estimate: Display delivery estimate such as "6 days" when available
- total_cents: retailer_price_cents + shipping_estimate_cents (0 when null) + estimate_buffer_cents (buffer-inclusive, fee-exclusive)
- service_fee_cents: Service fee in cents (order-level — added once per order, not per line; min $0.50, no maximum)
- checkout_total_cents: Final all-in total charged by POST /api/order (goods + service fee + order-processing fees). The ONE price to show the customer — identical for Lightning and card for buffered quotes like this one (exact Shopify quotes are the exception: Lightning charges less — see Exact Shopify Quote); any unused portion above the retailer's final cost is refunded after the order settles
- currency: "USD"
- product_url: Retailer product URL
- url: Retailer product URL
- thumbnail: Product image URL
- images: Array of product image URLs (primary image first; may be empty) — the full product image gallery
- is_prime: Whether the selected offer is Prime-eligible (Amazon only; false otherwise)
- variants: Variant options and a variant-hint array when available
- Products with a real variant choice (a dimension with more than one value) cannot be quoted unbound: the request 422s with the available options — re-quote with variant=[{"label","value"}] naming every dimension
- quote_token: Price quote token (valid 30 minutes) — include this on the matching product line in POST /api/order
- quote_expires_at: When the quote expires (ISO 8601)
Example:
GET /api/catalog/2101922242?retailer=walmart&zip=30312
GET /api/catalog/n4RTalM?retailer=nordstrom&zip=30312
### Quote by URL (FREE)
GET /api/catalog/quote
The quote endpoint for product lines whose identity is a retailer product URL rather than a first-class product ID: Shopify-merchant items and cross-retailer allowlist items (bestbuy, homedepot, lowes, costco, wayfair, macys, kohls, staples). Every such search result carries a ready-made quote_url pointing here — start from it, and when the buyer chose options (size, color, ...) append the variant param before requesting: a quote minted without the selection is unbound and checkout buys the page default. Shopify quote_urls are signed capabilities binding merchant, product, listing price, and an expiry; the signed token cannot be constructed by hand (append variant alongside it, never inside it), and an expired one means search again and use a fresh quote_url.
Query parameters for cross-retailer results (also constructible by hand):
- url (required): Percent-encoded product URL from the search result
- q (required): The original search query — the quote is minted by re-running the search and matching the URL, so the price is always fresh, never replayed
- zip (optional): Delivery ZIP code to associate with the quote
- variant (optional): JSON array of {"label","value"} pairs pinning the buyer's option choices (size, color, ...). Cross-retailer rows carry no option list to validate against, so the selection is accepted as given and applied at the retailer's checkout. A selection the retailer page cannot match fails the order as product_variant_required instead of shipping the page default; with a refund_destination on the order the charged amount is then refunded automatically, without one the failure response says how the payment is recovered. Always pass the buyer's explicit choices for products with options — omitting variant buys the page default.
Query parameters for Shopify-merchant results (baked into quote_url; not hand-constructible):
- source=shopify and quote={signed token}
- zip (optional): Delivery ZIP hint (the buffered Shopify total itself is ZIP-independent)
Response: JSON object { product, _note } where product carries the same fields as Quote One Product, including checkout_total_cents (the ONE price to show the customer), quote_token (valid 30 minutes), and quote_expires_at. The product_id is the product URL — always echo the product_id from THIS response (not the search result) on the matching line in POST /api/order. Shopify totals include a refundable buffer standing in for the store's shipping/tax; any unused portion is refunded to your refund_destination after the order.
Errors: 404 when the URL no longer appears in fresh search results (prices may have changed — search again and follow a fresh quote_url); 400/expired-token errors for missing or expired Shopify quote tokens; 429 when the per-IP Shopify quote rate limit is exceeded.
Example:
GET /api/catalog/quote?url=https%3A%2F%2Fwww.bestbuy.com%2Fsite%2F...&q=espresso+machine&zip=30312
### Exact Shopify Quote (FREE)
POST /api/catalog/quote
Upgrade a buffered Shopify quote to an address-exact total — item + shipping + tax priced by the merchant's own checkout — so the buyer is charged the real total instead of a blind buffer. Optional: the buffered quote from quote_url always works; prefer this when you already know the shipping address.
Required JSON body:
- quote (string): The signed Shopify quote token — the value of the "quote" query parameter inside the search result's quote_url
- variant (optional array): The buyer's option choices as {"label","value"} pairs, same as the GET variant param. Pass it whenever the buyer chose options — omitting it exact-quotes the variant embedded in the signed token, often the default
- shipping_address (object): Same shape as POST /api/order's shipping_address
The address travels in the body rather than the URL so buyer PII stays out of request logs.
Response: JSON object { product, _note } with the same quote fields as Quote by URL. total_cents is the merchant's exact checkout total (item + shipping + tax) with no quote buffer or safety margin; checkout_total_cents adds the standard service fee plus order-processing/payment fees and is the all-in CARD charge. A Lightning/wallet payment of an exact quote is charged less — the true total plus service fee and the flat order-processing fee, with no card-processing fees — so the authoritative wallet figure is the order preview's charge_amount_cents (and the 402 challenge amount matches it). If the store's price rises between quote and order, the order fails and the full amount is refunded to your refund_destination.
Fallback: when the merchant cannot price the address headlessly, the response carries the ordinary buffered quote plus an exact_quote_unavailable field naming the reason — checkout still proceeds with the buffered total.
Errors: 400 for an invalid or incomplete shipping_address; 429 when the per-IP Shopify quote rate limit is exceeded.
### Preview Order (read-only)
POST /api/order/preview
Price a whole basket as one order WITHOUT paying. Not L402-protected and it does NOT r