Agent Integration

Claude Commerce Agents on Kifly

Anthropic's commerce-agents blueprint ships a shopping agent and leaves one interface empty — StorefrontBackend — because it expects you to bring your own catalog, cart and payments. Their docs put it plainly: "the blueprint leaves payment to you."

Kifly is what goes there.

Hand this to your coding agent

Paste this into Claude Code, Cursor, or whatever you build with. It is self-contained — the two things that are easy to get wrong are stated inline, so your agent does not have to guess them.

Implement Anthropic's commerce-agents StorefrontBackend
(github.com/anthropics/commerce-agents) against the Kifly API.

Base URL: https://kifly.ai
Auth: Authorization: Bearer $KIFLY_API_KEY
Every mutating call needs an Idempotency-Key header (a fresh UUID).

Method -> endpoint:
  search_products          GET    /api/agent/search?q=&limit=
  get_product_details      GET    /api/agent/products?id=
  get_cart                 GET    /api/agent/cart/{cart_id}
  add_to_cart              POST   /api/agent/cart/{cart_id}/items  {variant_id, quantity}
  update_cart_item         PATCH  /api/agent/cart/{cart_id}/items/{item_id}  {quantity}
  remove_from_cart         DELETE /api/agent/cart/{cart_id}/items/{item_id}
  checkout_handoff         POST   /api/agent/cart/{cart_id}/checkout
  get_preferences          GET    /api/agent/buyer/me
  get_orders               GET    /api/agent/buyer/orders
  get_fulfillment_options  GET    /api/agent/seller?handle=
  (to open a cart)         POST   /api/agent/cart  {seller_handle}

Get these three right:

1. Two price units. The catalog returns major units (offers.price = 28.0).
   The cart returns cents (unit_price_cents = 2800). Convert on the cart side
   only. Getting this backwards quotes a $28 item at 28 cents and nothing
   errors.

2. One cart per seller. Keep a session -> {seller_handle: cart_id} map. A
   product's seller is kifly:seller on the search result. get_cart reads every
   cart the session holds and merges them into one basket; checkout_handoff
   returns one CheckoutHandoff per seller with its `seller` field set.

3. add_to_cart takes kifly:variantId, not @id. A product carrying
   kifly:productOptions is a family: return it with `options` set and the
   blueprint's own cart gate will steer the model to a variant.

On a 5xx or timeout, raise. Never return an empty list — the agent will tell
the shopper the store carries nothing.

search_policies: return []. Kifly has no policy corpus, and an empty list is
what makes the agent decline a store-terms question instead of inventing one.

Reference: https://kifly.ai/docs/commerce-agents

What backs each method

`StorefrontBackend` method	Backed by
`search_products`	Multilingual semantic search across the catalog
`get_product_details`	Full record with option matrix and purchasable variants
`get_cart` / `add_to_cart` / `update_cart_item` / `remove_from_cart`	Kifly carts
`checkout_handoff`	A payment link per seller, or a handoff to their own storefront
`get_preferences` / `get_orders` / `get_order`	Buyer identity and order history
`get_fulfillment_options`	Per-seller delivery coverage, fees, and pickup
`search_policies`	Not provided — return `[]`

You also get something the blueprint has no interface for: your agent is not limited to one store. A single-store deployment sells one catalog. On Kifly the same agent searches every seller, and each one still gets paid correctly.

Reading a search result

{
  "@type": "ItemList",
  "itemListElement": [{
    "item": {
      "@id": "prod_coffee",
      "name": "Ethiopian Dark Roast",
      "kifly:variantId": "variant_coffee_12oz",
      "kifly:seller": "mayas-coffee",
      "offers": {
        "price": 28.0,
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock",
        "kifly:purchasable": true
      }
    }
  }]
}

A variant with no offers block inherits the family price. Absent means "same price", never "unpriced".
kifly:purchasable: false is discovery-only — real and in stock, but checkout hands off to the seller's own site.
kifly:suggestions holds near-misses, deliberately outside itemListElement. Don't merge them into results.

Auth

Three credential types, same as the rest of the API — see MCP Integration for which to pick:

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx
Idempotency-Key: <a-uuid-you-generate-per-request>

Get a key from the seller dashboard → Developer → API Keys. Building a buyer agent that shops the whole network rather than one store? Use OAuth 2.1 or a network key instead — no Kifly account needed to register a client.

Want the Python reference implementation of this backend? Get in touch.