{"openapi":"3.1.0","info":{"title":"Ziffi Commerce API","description":"One API for cross-brand product discovery, pricing, and commerce over every Shopify brand in the Ziffi graph. A free tier lets you try it with no signup (one shared rate limit per IP). Sign up for an `X-Ziffi-Key` to use your key's own higher limit and to attribute usage to your app. Every response is enveloped `{data, provenance, as_of, tier}`; the graph tier is cacheable (ETag), the live tier (price/coupons) is fetched per request.","version":"1.0","contact":{"name":"Ziffi Developers","url":"https://dev.ziffi.xyz"}},"paths":{"/v1/search":{"get":{"tags":["v1"],"summary":"Search","description":"Top results for a query. Capped, no pagination, no total count returned (anti-enumeration): a\nquery gives you the best matches, not a way to walk the catalogue.","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"free-text query","default":"","title":"Q"},"description":"free-text query"},{"name":"price_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Min"}},{"name":"price_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Max"}},{"name":"in_stock","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock"}},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"}},{"name":"on_sale","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"On Sale"}},{"name":"facets","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON object, e.g. {\"color\":\"navy\"}","title":"Facets"},"description":"JSON object, e.g. {\"color\":\"navy\"}"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"relevance","title":"Sort"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"hybrid | lexical | semantic — which arms run","default":"hybrid","title":"Mode"},"description":"hybrid | lexical | semantic — which arms run"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"description":"top results for this query (no pagination)","default":20,"title":"Limit"},"description":"top results for this query (no pagination)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}":{"get":{"tags":["v1"],"summary":"Product","operationId":"product_v1_products__ident__get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"comma list of includes","title":"Include"},"description":"comma list of includes"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}/price":{"get":{"tags":["v1"],"summary":"Product Price","description":"LIVE tier — client-preferred (storefront fetches from the user's browser); this server path is\nthe bounded fallback + the answer for browserless API/MCP consumers.","operationId":"product_price_v1_products__ident__price_get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/prices":{"post":{"tags":["v1"],"summary":"Prices","description":"Batch live price for a basket. Bounded fan-out (≤20); each entry carries its own `verified`.","operationId":"prices_v1_prices_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_prices_v1_prices_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/coupons":{"get":{"tags":["v1"],"summary":"Coupons","description":"LIVE — discover discount codes that actually work on a brand's Shopify store by testing candidate\ncodes at the live cart (Honey/Coupert-style). Pass ONE of `product`, `brand`, or `domain`. Applicable\ncodes are ranked best-first with the discount each takes off a single-item cart (integer minor units).","operationId":"coupons_v1_coupons_get","parameters":[{"name":"product","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"product_uid (sha:…) or product id (uuid)","title":"Product"},"description":"product_uid (sha:…) or product id (uuid)"},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"brand slug (or its domain)","title":"Brand"},"description":"brand slug (or its domain)"},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"raw Shopify host, e.g. mcaffeine.com","title":"Domain"},"description":"raw Shopify host, e.g. mcaffeine.com"},{"name":"max_candidates","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":40,"title":"Max Candidates"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/suggest":{"get":{"tags":["v1"],"summary":"Suggest","operationId":"suggest_v1_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/recommend":{"get":{"tags":["v1"],"summary":"Recommend","operationId":"recommend_v1_recommend_get","parameters":[{"name":"product_id","in":"query","required":true,"schema":{"type":"string","title":"Product Id"}},{"name":"intent","in":"query","required":false,"schema":{"type":"string","default":"related","title":"Intent"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":12,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}/reviews":{"get":{"tags":["v1"],"summary":"Product Reviews","operationId":"product_reviews_v1_products__ident__reviews_get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plans":{"get":{"tags":["v1"],"summary":"Plans","description":"The access policy — a free tier for anonymous callers, higher limits with a key (discovery).","operationId":"plans_v1_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/quota":{"get":{"tags":["v1"],"summary":"Quota","description":"Your current rate limit: the free tier if anonymous, or this key's own limit if a key is sent.","operationId":"quota_v1_quota_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/me":{"get":{"tags":["v1"],"summary":"Me","description":"Who this key is + its usage today. The developer dashboard reads this.","operationId":"me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cart":{"post":{"tags":["v1"],"summary":"Cart Create","description":"Create a multi-brand cart. `{ items:[{product_id, variant_id?, qty}], email? }` → grouped cart\n(per-brand subtotal + checkout link + combined total). Lines live in each brand's Shopify cart.","operationId":"cart_create_v1_cart_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cart/{cart_id}":{"get":{"tags":["v1"],"summary":"Cart Get","operationId":"cart_get_v1_cart__cart_id__get","parameters":[{"name":"cart_id","in":"path","required":true,"schema":{"type":"string","title":"Cart Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cart/{cart_id}/lines":{"post":{"tags":["v1"],"summary":"Cart Lines","description":"Add lines: `{ items:[{product_id, variant_id?, qty}] }` (a new brand spins up its own Shopify cart).","operationId":"cart_lines_v1_cart__cart_id__lines_post","parameters":[{"name":"cart_id","in":"path","required":true,"schema":{"type":"string","title":"Cart Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cart/{cart_id}/discount":{"post":{"tags":["v1"],"summary":"Cart Discount","description":"Apply a discount code (`{ code, brand? }`). Each group's `discount_codes[].applicable` is\nShopify's truth; `discount_minor` is the amount taken off.","operationId":"cart_discount_v1_cart__cart_id__discount_post","parameters":[{"name":"cart_id","in":"path","required":true,"schema":{"type":"string","title":"Cart Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cart/{cart_id}/address":{"post":{"tags":["v1"],"summary":"Cart Address","description":"Set delivery address (`{ zip, country?, province?, city? }`) → per-brand delivery options.","operationId":"cart_address_v1_cart__cart_id__address_post","parameters":[{"name":"cart_id","in":"path","required":true,"schema":{"type":"string","title":"Cart Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout":{"post":{"tags":["v1"],"summary":"Checkout","description":"Path A: `{ cart_id }` → each brand's own `checkout_url` + a signed attribution token. The buyer\npays on the brand's checkout (we are the rails, not the merchant of record).","operationId":"checkout_v1_checkout_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/{action}":{"post":{"tags":["v1"],"summary":"Account","description":"Federated login. `POST /v1/account/register|login { email, password, brand }` creates/logs in a\nper-brand Shopify shadow customer and caches its access token against the Ziffi identity.","operationId":"account_v1_account__action__post","parameters":[{"name":"action","in":"path","required":true,"schema":{"type":"string","title":"Action"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipping":{"get":{"tags":["v1"],"summary":"Shipping","description":"Shipping for a product+pincode: free-ship threshold / COD / tiers from `brand.shipping`, and the\nper-pincode ETA from the cached delivery matrix (runtime lookup — never a per-pincode network call).","operationId":"shipping_v1_shipping_get","parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string","description":"product_uid (sha:…) or id (uuid)","title":"Product"},"description":"product_uid (sha:…) or id (uuid)"},{"name":"pincode","in":"query","required":true,"schema":{"type":"string","description":"6-digit delivery pincode","title":"Pincode"},"description":"6-digit delivery pincode"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/discover":{"post":{"tags":["v1"],"summary":"Discover","description":"§17 hero — AI-native cross-brand discovery. `{ query, budget_max_minor?, brand?, limit?, context? }`\n→ shoppable cards each with a `why` and an `add_to_cart` link. LLM parses intent → hybrid retrieval →\ndeterministic explanation; degrades to raw hybrid search if the model is unavailable.","operationId":"discover_v1_discover_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/mcp":{"post":{"tags":["mcp"],"summary":"Mcp","operationId":"mcp_v1_mcp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_prices_v1_prices_post":{"properties":{"idents":{"items":{"type":"string"},"type":"array","title":"Idents","description":"≤20 product ids/uids"}},"type":"object","required":["idents"],"title":"Body_prices_v1_prices_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ZiffiKey":{"type":"apiKey","in":"header","name":"X-Ziffi-Key","description":"Optional on the free tier. Sending your key applies your key's own (higher) rate limit instead of the shared free-tier limit, and attributes usage to your app."}}},"tags":[{"name":"Discover","description":"Search, browse, suggest, recommend across every brand."},{"name":"Understand","description":"Product detail, attributes, reviews."},{"name":"Price","description":"Live price, batch prices, coupons — live tier, never cached."},{"name":"Platform","description":"Access policy, quota, health, OpenAPI."}],"servers":[{"url":"https://dev.ziffi.xyz","description":"Ziffi API"}]}