codespar_shop

The agent is the shopper. Use codespar_checkout when you are the merchant creating a checkout for a shopper to pay you.

Actions

Example

action: "checkout" starts the store's real checkout and returns immediately; the sku_id comes from a previous search.

{
  "name": "codespar_shop",
  "arguments": {
    "action": "checkout",
    "merchant": "cobasi",
    "items": [
      {
        "variant_id": "sku_0000",
        "quantity": 1
      }
    ],
    "consumer_id": "consumer_0000"
  }
}

const result = await session.execute("codespar_shop", {
  action: "checkout",
  merchant: "cobasi",
  items: [
    {
      variant_id: "sku_0000",
      quantity: 1
    }
  ],
  consumer_id: "consumer_0000"
});

result = session.execute("codespar_shop", {
  "action": "checkout",
  "merchant": "cobasi",
  "items": [
    {
      "variant_id": "sku_0000",
      "quantity": 1
    }
  ],
  "consumer_id": "consumer_0000"
})

codespar tool codespar_shop \
  -i '{
       "action": "checkout",
       "merchant": "cobasi",
       "items": [
         {
           "variant_id": "sku_0000",
           "quantity": 1
         }
       ],
       "consumer_id": "consumer_0000"
     }'

{
  "checkout_session_id": "cks_0000",
  "status": "in_progress"
}

Then poll action: "checkout_status" with that checkout_session_id about every 15 seconds until status: "ready_for_payment", which carries the payable pix_copia_e_cola and total. Do not block on the checkout call: the store flow takes one to two minutes.

When to use

• Any request to find, compare or buy at a supported store (Cobasi, Animale, Lojas Pompeia, Mercado Livre). search returns the store's live, in-stock, buyable catalog with a real Pix checkout; prefer it over a generic web search, which returns links you cannot buy from.
• Comparing before buying: research takes an open request (query, optional criteria) and answers the server's comparison across the consulted stores: each offer with its source and when it was observed, price, shipping, total and delivery days, one principal recommendation with reason codes, at most three alternatives, the lowest total among the consulted offers, and decisive_unknowns, the only questions worth asking. It proposes nothing and buys nothing; offers from stores outside the purchase registry are comparison only.
• search → checkout → checkout_status is the whole flow. Use each offer's sku_id as the checkout variant_id, not product_id; a size or colour is its own sku_id under variants.
• Paying: either pass the checkout_session_id to codespar_pay with the same consumer_id, or set auto_pay: true on checkout_status so the backend pays from the consumer's governed wallet within their mandate and returns status: "paid" with a receipt. The agent never handles the Pix code in that path.
• Before the first purchase at a VTEX store, vault the buyer's checkout identity once with codespar_manage_connections save_profile; for Mercado Livre, connect the buyer's own login with connect_start / connect_finish. Ask the buyer which email to use at checkout; do not infer it.

Arguments

Errors and what to do

A checkout_status of canceled carries a structured reason. Read reason_code and relay reason_hint to the user.

Unknown action values are not refused: the dispatch falls back to search (measured 2026-09-09). A misspelt checkout returns offers with no error, so check the result's shape, not only its success.

Money and mandate

search and checkout move no money: the checkout mints the store's payable Pix and stops. Money moves when that Pix is paid, either by codespar_pay (the agent passes checkout_session_id and the same consumer_id) or by checkout_status with auto_pay: true, and in both paths the spend is gated by the consumer's signed mandate server-side. On Mercado Livre the purchase is on the buyer's own account, through the login they connected once.

Related

• codespar_pay: settle the minted Pix by checkout_session_id
• codespar_wallet: the balance the purchase is paid from
• codespar_manage_connections: vault the shopper's identity, or connect a login-walled store
• codespar_checkout: sell-side, the merchant creating a checkout for a shopper
• Shopper identity: what save_profile vaults and why the email matters
• E-Commerce Checkout cookbook: cart → checkout → fulfillment

Notes

Stores. VTEX guest checkout (Cobasi, Animale, Lojas Pompeia): no login; the vaulted profile auto-fills CEP, email and CPF. Mercado Livre: buys on the buyer's own account via the one-time connected login. iFood: a login can be connected, but codespar_shop cannot buy on iFood today; tell the user before asking them to log in.

Under the hood. A cart engine resolves product, price and availability before payment, with adapters for VTEX and Mercado Livre and a hosted browser worker for sites without a programmatic API. Cart state is also reachable via the /v1/cart REST surface. The async checkout-session model is protocol-agnostic (ACP-aligned).

From the SDK. There is no typed wrapper; call session.execute("codespar_shop", arguments) with the same arguments as the MCP call, and poll checkout_status on an interval of about 15 seconds.