{"openapi":"3.1.0","info":{"title":"x402 Swag storefront API","description":"Agent-friendly e-commerce API. Browsing, cart, and checkout are free; orders are paid per-order via x402 (USDC on Base) at a dynamic price, or by card via Stripe. Carts work two ways: keep the Set-Cookie from your first cart call (browsers), or run stateless — every cart/checkout call accepts the cart id from GET /api/cart via the X-Cart-Id header, a cart_id body field, or ?cart_id= (agents).","version":"1.0.0"},"servers":[{"url":"https://x402swag.com"}],"paths":{"/api/products":{"get":{"summary":"List active products (free)","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search title/tags/handle"},{"name":"limit","in":"query","schema":{"type":"integer","maximum":250,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Products with variants, images, prices (USD strings)"}}}},"/api/products/{handle}":{"get":{"summary":"Get one product by handle (free)","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product"},"404":{"description":"Not found or inactive"}}}},"/api/collections":{"get":{"summary":"List published collections (free)","responses":{"200":{"description":"Collections"}}}},"/api/collections/{handle}":{"get":{"summary":"Get a collection and its products (free)","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection + products"},"404":{"description":"Not found"}}}},"/api/cart":{"get":{"summary":"Get (or create) a cart (free) — the returned id is reusable statelessly","parameters":[{"name":"X-Cart-Id","in":"header","schema":{"type":"string"},"description":"Stateless alternative to the cart cookie: the cart id returned by GET /api/cart or /api/cart/add"},{"name":"cart_id","in":"query","schema":{"type":"string"},"description":"Same as X-Cart-Id"}],"responses":{"200":{"description":"Cart (response includes its id)"},"404":{"description":"Supplied cart id unknown"}}}},"/api/cart/add":{"post":{"summary":"Add a variant to the cart (free)","parameters":[{"name":"X-Cart-Id","in":"header","schema":{"type":"string"},"description":"Stateless alternative to the cart cookie: the cart id returned by GET /api/cart or /api/cart/add"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"integer"},"quantity":{"type":"integer","default":1},"cart_id":{"type":"string","description":"Stateless alternative to the cart cookie / X-Cart-Id header"}}}}}},"responses":{"200":{"description":"Updated cart"},"404":{"description":"Supplied cart id unknown"},"422":{"description":"Bad variant / out of stock"}}}},"/api/checkout/rates":{"get":{"summary":"Shipping rates for the current cart (free; live provider quote when available)","parameters":[{"name":"X-Cart-Id","in":"header","schema":{"type":"string"},"description":"Stateless alternative to the cart cookie: the cart id returned by GET /api/cart or /api/cart/add"},{"name":"cart_id","in":"query","schema":{"type":"string"},"description":"Same as X-Cart-Id"},{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"province","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"zip","in":"query","schema":{"type":"string"}},{"name":"address1","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{rates:[{id,name,price}], live:boolean} — rate ids may be numbers or strings"}}}},"/api/checkout":{"post":{"summary":"Create an order from the cart (free) — response contains payment instructions","parameters":[{"name":"X-Cart-Id","in":"header","schema":{"type":"string"},"description":"Stateless alternative to the cart cookie: the cart id returned by GET /api/cart or /api/cart/add"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","shipping_address"],"properties":{"email":{"type":"string","format":"email"},"cart_id":{"type":"string","description":"Stateless alternative to the cart cookie / X-Cart-Id header"},"shipping_address":{"type":"object","required":["country"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string","description":"State/province code, e.g. TX"},"zip":{"type":"string"},"country":{"type":"string","description":"ISO-2 country code, e.g. US"}}},"billing_address":{"type":"object","required":["country"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string","description":"State/province code, e.g. TX"},"zip":{"type":"string"},"country":{"type":"string","description":"ISO-2 country code, e.g. US"}}},"shipping_rate_id":{"type":"string","description":"From /api/checkout/rates; e.g. 2 or printify:standard"},"discount_code":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"201":{"description":"{order, payment:{gateway,pay_url,...}, payment_methods:[x402|stripe], status_url}"},"422":{"description":"Validation error (empty cart, missing address, bad rate)"},"503":{"description":"Checkout disabled (preview mode)"}}}},"/api/orders/{token}":{"get":{"summary":"Order status by token (free) — tracking numbers appear after fulfillment","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"},"404":{"description":"Unknown token"}}}},"/api/orders/{token}/pay":{"post":{"summary":"Pay an order with x402 (USDC on Base) — dynamic price","description":"First POST returns 402 with a PAYMENT-REQUIRED challenge priced at the order total. Sign the USDC authorization with an x402 client and retry with the X-PAYMENT header. Settlement marks the order paid and triggers fulfillment.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ok:true, order} — payment settled (idempotent for already-paid orders)"},"402":{"description":"Payment required — challenge in PAYMENT-REQUIRED header + JSON body"},"404":{"description":"Unknown token"},"422":{"description":"Order cancelled"}}}},"/api/orders/{token}/stripe":{"post":{"summary":"Create a hosted Stripe Checkout session for an order (card payments, humans)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{checkout_url} — redirect the buyer there"},"422":{"description":"Below card minimum ($0.50) or Stripe error"},"503":{"description":"Card payments not configured"}}}},"/api/agent/catalog":{"get":{"summary":"Full agent-ready catalog in one paid call (x402, flat price)","description":"One-shot catalog for autonomous agents: every active product with variant ids and prices, collections, and the exact buy flow. Pays via x402 — this is the store's Bazaar-discoverable front door. Everything it returns is also available free via the endpoints above; pay only if you want it in one round trip.","responses":{"200":{"description":"{store, products, collections, how_to_buy}"},"402":{"description":"Payment required (x402 challenge)"},"503":{"description":"x402 not configured"}}}}},"externalDocs":{"description":"Agent guide","url":"https://x402swag.com/llms.txt"}}