Kifly — Agentic Commerce & Payments MCP

Search or browse Kifly's product catalog. Multilingual semantic search (100+ languages). Returns a JSON-LD ItemList with kifly:totalCatalogSize. When empty, kifly:emptyReason is 'empty_catalog' | 'no_matches_for_query' — on 'no_matches_for_query' tell the buyer nothing matched rather than guessing, then offer kifly:suggestions (related products — NOT matches) and kifly:availableCategories

Create a new shopping cart on Kifly. For network (cross-seller) tokens you MUST pass seller_handle — each cart is bound to exactly one seller. Get the handle from search_products results (every item's kifly:seller IS the handle in network results) or get_seller. Seller-scoped tokens may omit the handle — their own seller is implicit. Returns a cart_id to use with add_to_cart and checkout.

Requires checkout:write scope. Add a product variant to an existing cart. Use the variant_id from search_products results. Returns full cart state including item_ids you can use with update_cart_item. Max quantity per item and max cart total are enforced — call get_platform_limits to check the current limits before building a large cart. Exceeding the per-item limit returns 400 `QUANTITY_E

Inspect the current state of a cart — line items, quantities, prices, and shipping address. Each item includes an item_id you can pass to update_cart_item to change quantity or remove the item. Call this after add_to_cart to review the cart before checkout, or any time the buyer asks what's in the cart. kifly_purchasable: false (fulfillment: "external") means checkout on this cart will h

Requires checkout:write scope. Change the quantity of a line item in an open cart, or remove it entirely. Set quantity to 0 to remove the item. Get the item_id from get_cart or the cart field in the add_to_cart response. Returns the updated cart state. The per-item quantity ceiling applies here too — call get_platform_limits to check the current limit. Exceeding it returns 400 `Q

Requires checkout:write scope. Persist a shipping address on the cart and confirm whether the seller can deliver to it. Call BEFORE checkout. Returns delivery_eligible: true/false. When false, delivery_coverage: { states, cities } tells you exactly which US states and cities the seller covers — tell the buyer where coverage is available. When true, returns `cart_total_with_delivery_cen

Requires cart:write scope. Create a cart, add items, and set the shipping address in ONE call — the fast path when you already know the seller, the exact variant(s), and the buyer's address (e.g. a reorder, or a buyer who has decided). Prefer this over the create_cart → add_to_cart → set_shipping_address sequence to save round trips; those granular tools stay available for exploratory, multi-ste

Requires checkout:write scope. Requires set_shipping_address to have been called first. Returns 400 invalid_shipping if no address is on the cart, or 400 delivery_unavailable if the buyer's address is outside the seller's coverage. Cart total must not exceed the platform cap (kifly://platform/limits). **Checkout is always human-in-the-loop: it returns a link the buyer opens and confi

Start registering a buyer so they can be recognized across future purchases without re-entering their details. Takes the buyer's email and name and always emails a 6-digit verification code — the response is { verification_required: true, buyer_profile_id } whether the email is brand new or already has an account (so this call alone never reveals which). Ask the buyer to read you the code from t

Send a 6-digit verification code to a returning buyer's email so they can prove the account is theirs and recover their saved name + shipping address on this connection — without pasting any token or re-entering their name. Call this when the buyer says they've shopped with Kifly before and gives you their email; then ask them to read you the code from their inbox and call verify_buyer. Alwa

Verify the 6-digit code a returning buyer received by email (from request_buyer_code). On success returns { buyer_token, buyer_profile_id } — pass the buyer_token to get_buyer_profile to auto-fill their saved name + shipping address, and to checkout to pre-fill their email on the payment link. Fails with invalid_otp if the code is wrong or expired (ask them to re-check, or call `reques

Retrieve a repeat buyer's saved name, email, and default shipping address. At the start of every purchase flow, ask the buyer in plain language: 'Are you a returning Kifly shopper? What's the email on your Kifly account?' — never ask them to paste a token. If they have a Kifly account, recover it by email: call request_buyer_code with their email, ask them for the 6-digit code we email them,

List a returning buyer's recent orders and their current fulfillment status — use this in a NEW session to answer 'did my order ship?' / 'where's my package?' when you don't have the original session_id from checkout. Requires the buyer's buyer_token (recover it via request_buyer_code + verify_buyer if you don't have one). Returns { orders, count }, newest first; each order has `status

Save a shipping address to the buyer's Kifly profile so it auto-fills on future purchases. Call this after a successful checkout if get_buyer_profile returned default_shipping_address: null. The address is persisted server-side against the buyer token — the buyer never needs to re-enter it. Use the same address that was passed to set_shipping_address for this order.

Send structured feedback to the Kifly team. Call after a confusing response, a dead-end, or a successful workaround you had to invent — it's how we improve the agent surface. Fire-and-forget: returns 202 immediately, no blocking, safe to skip if it would add latency to a user-facing flow. category and severity are required enums (don't free-form them). Include context with what you were

Submit the buyer's product/feature request to the Kifly team. Use this when the buyer wishes Kifly *itself* did something it doesn't — a missing capability, a rough flow, an idea to improve the platform. This is NOT submit_feedback (that's for reporting a broken/confusing API response you hit). Requires the buyer's kfb_live_ token — only registered buyers can file requests. Help the bu

Retrieve a seller's public profile: name, location (city/region/country), storefront URL, delivery fee, delivery coverage, and catalog size. Call this before create_cart or set_shipping_address to validate that the seller ships to the buyer's area or to set expectations about catalog size. delivery_coverage is { states, cities, nationwide, state_count, city_count, coverage_configured }

List all active sellers on the Kifly network. Requires a network token (kfn_live_…). Returns each seller's handle, name, city, region, delivery coverage (nationwide:true or a states list), delivery fee, and catalog size. delivery_coverage.cities may be capped to a handful of entries — compare cities.length against city_count; if fewer, call get_seller for that seller's full city li

Returns the current platform-enforced cart limits: max_item_quantity (per-line-item ceiling), max_cart_total_cents, and max_cart_total_usd. Call this once at session start before building a large cart so you can quote limits to the buyer proactively rather than discovering them via errors. The limits are operator-configurable; always read them at runtime rather than hardcoding.

No parameter schema on file.

Check the status of a Stripe checkout session. Poll every 5 seconds after checkout until status is 'paid', 'shipped', or 'failed'. Returns order details (order_id, amount, items) when paid. When the seller marks the order as shipped, status becomes 'shipped' and tracking_number, carrier, and shipped_at are included — share these with the buyer. Call get_help if the buyer needs Kifly's support cont

Get Kifly's website and support contact email. Call this if you are stuck, hit an unresolvable error, or the buyer asks how to reach a human. Returns the website URL and support email — always share both with the buyer.

No parameter schema on file.