Agent Integration

Kifly shopping playbook

Kifly is a catalog of independent online stores that AI agents can search and buy from over MCP (https://kifly.ai/api/mcp) or REST (https://kifly.ai/api/agent/*). No account is needed to search, build a cart or get a payment link.

1. The user named a store or a website

Ask Kifly before you open a browser. One call:

MCP: get_seller with domain (any URL on the store's site works) or name
REST: GET /api/agent/seller?domain=theirstore.com or ?name=Their Store

Answer	What it means	Do this
200, `fulfillment: "kifly_checkout"`	Kifly can sell it	Go to step 3 with `seller_handle`
200, `fulfillment: "external"`	Kifly lists it; the store takes payment on its own site	Step 3; checkout returns links to the store's site
404 `SELLER_NOT_FOUND`, `details.did_you_mean` not empty	Close to a store Kifly carries	Ask the user which one. Never pick for them
409 `SELLER_AMBIGUOUS`	Several stores share that name	Ask which one; `details.candidates` lists their domains
404 `SELLER_NOT_FOUND`, `did_you_mean` empty	Kifly does not carry this store yet	Tell the user, then use the store's own site. Check its product pages for JSON-LD before driving a browser

2. The user named only a product

search_products across the network, then compare. Prices are item prices; delivery is priced when an address is set (step 4).

Some results may be marked kifly:offNetwork: products from outside retailers, found through affiliate programs, ranked alongside Kifly sellers'. Tell the user what the list's kifly:affiliateDisclosure says (they are not Kifly sellers; Kifly may earn a commission), then cart them like any other product. Checkout returns the retailer's link for each instead of a payment link.

3. Find the product

search_products with seller_handle from step 1. Read kifly:verifiedAt on each result: it is when Kifly last confirmed the listing against the store's own site.

4. Cart and delivery

create_cart for that seller.
add_to_cart with the product and variant.
set_shipping_address with the buyer's address. It quotes delivery and says if the seller does not ship there. Skip it when fulfillment is "external": the store collects the address on its own site. shipping_priced_at: "merchant_checkout" means the store prices shipping at its own checkout; say so, never quote it as free.

5. Checkout

checkout returns a payment link. The human opens it and pays. Nothing is charged until they do. For a store with fulfillment: "external", checkout returns one link per item to the store's own site instead.

6. After payment

order_status with the checkout session id tells you whether it was paid, and tracking once the seller ships. Never tell the user a purchase is complete before it says so.

Rules

Never invent a product fact: price, size, stock, materials or shipping. If Kifly does not have it, say so.
Never complete a payment without the human.
Every error carries code, fix and retryable. Branch on code; the prose is for people.
Stuck, or something Kifly should do better: submit_feedback. A human reads every report.