Kifly — Agentic Commerce & Payments

Search or browse Kifly's product catalog across every seller on the network. Multilingual semantic search (100+ languages); omit `q` to browse recent listings. Pass `q` as an array (up to 5) to try se…

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 …

Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Add a product variant to an existing cart. Use the variant_id from search_products results. Returns full cart state including item_ids …

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. Ca…

Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. 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` fr…

Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Persist a shipping address on the cart and confirm the seller can deliver to it. **Call BEFORE `checkout`.** Returns `delivery_eligible…

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 …

Requires `checkout:write` **or** the narrower `checkout:link` scope — and **no API key at all** works too: send `meta.ucp-agent.profile` and you get the same payment link (a tokenless caller holds `ch…

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 resp…

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…

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-…

Retrieve a repeat buyer's saved name, email, and default shipping address, given their `buyer_token`. Use them to auto-fill `set_shipping_address`, and pass the token to `checkout` so Stripe pre-fills…

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…

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`.** T…

Send structured feedback to the Kifly team. **No API key required** — send `meta.ucp-agent.profile` and this works with no credential at all. **Call after a confusing response, a dead-end, or a succes…

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 pl…

Retrieve a seller's public profile: name, location (city/region/country), storefront URL, delivery fee, delivery coverage and catalog size. `verified_domains`: domains the seller proved it controls; a…

The seller's published returns, shipping and warranty policy, in their own words. **Call before telling a buyer what happens after purchase** — if it is not here, say so; never infer a typical policy.…

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), del…

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 larg…

No key needed for your own session: send the profile you checked out with. Check the status of a Stripe checkout session. Poll every 5 seconds after checkout until status is 'paid', 'shipped', or 'fai…

Get unstuck. Returns Kifly's website and support email for the BUYER, plus how to report the problem to Kifly's engineers yourself. Call this if you are stuck, hit an unresolvable error, or the buyer …

Current cart constraints: max quantity per line item and max cart total (cents + USD). Read before starting a purchase flow to avoid rejection mid-checkout.

How delivery_coverage works: the four coverage cases (nationwide, state list, not-configured, merchant-managed), where cities are capped, and how eligibility and fees are quoted.

Field-level reference for search_products / browse results: the kifly:sellers map, the three delivery-coverage cases, variant and option-axis alignment, capped fields, and every kifly: extension. Fetc…

Field-level reference for checkout results: the three payment_rail outcomes and what each does and does not carry, the directory handoff object, buyer_token_status, and every refusal code with its ret…

The email-code sequence that recovers a returning buyer's saved name, email and shipping address (request_buyer_code → verify_buyer → get_buyer_profile), the one-click sign-in alternative, and what to…

The HTTP surface: the UCP-Agent header in both accepted wire forms, the endpoints open without a credential, idempotency, and the error envelope. Read this if a request is refused and you cannot tell …

Every stable error `code` the API returns, what causes it, and whether it is retryable. Read this before treating a failure as permanent.

Which credential fits what you are building, what a tokenless agent can reach, and the recommended purchase flow.

Interactive product cards for search_products results.