Buy-side shopping — act as the shopper to search a store's catalog and buy a product, minting the store's real Pix. VTEX guest checkout and Mercado Livre. Call via session.execute().

codespar_shop

Meta-tool

codespar_shop is the buy-side primitive: the agent acts as the shopper, searching a store's catalog and buying a product, minting the store's real Pix copia-e-cola to settle from the governed wallet (via codespar_pay × pix). Use codespar_checkout when you are the merchant creating a checkout for a shopper to pay you.

Actions

`action`	What it does
`search`	Returns card-ready offers for a merchant query — each with `product_id`, `sku_id` (use THIS as the checkout `variant_id`), price, and variants
`checkout`	STARTS the store's real checkout (a 1-2 min browser flow) and returns immediately with `{ checkout_session_id, status: "in_progress" }` — do not block
`checkout_status`	Poll with the `checkout_session_id` every ~15s until `status: "ready_for_payment"`, which returns the payable `pix_copia_e_cola` + total

A status: "canceled" carries a structured reason: retriable: true (store_temporarily_unavailable / checkout_failed) is a temporary store fault — retry the checkout; only no_shipping is a genuine out-of-stock/no-delivery. identity_required → use a different checkout email; not_connected → connect the account first. This async checkout-session model is protocol-agnostic (ACP-aligned).

Stores

Store	Flow
VTEX guest checkout (Cobasi, Animale, Lojas Pompeia)	No login — vault the buyer's checkout identity once via `codespar_manage_connections` (`save_profile`) so later buys don't re-ask for CEP / email / CPF
Mercado Livre	Buys on the buyer's own account via a one-time connected login (`codespar_manage_connections` `connect_start` / `connect_finish`)

Behind the meta-tool, a cart engine resolves product, price, and availability before payment — with adapters for VTEX, Mercado Livre, and a hosted browser-worker for sites without a programmatic API. Cart state is also reachable directly via the /v1/cart REST surface. codespar_shop mints the store's payable Pix; settle it with codespar_pay using method: "pix".

Direct execute

There is no typed wrapper for codespar_shop yet — call via session.execute().

// 1) search a store's catalog
const found = await session.execute("codespar_shop", {
  action: "search",
  merchant: "cobasi",
  query: "ração golden 15kg",
});

// 2) START the store's real checkout — returns immediately, do not block
const started = await session.execute("codespar_shop", {
  action: "checkout",
  merchant: "cobasi",
  items: [{ variant_id: found.offers[0].sku_id, quantity: 1 }],
});

// 3) poll until the store's payable Pix is ready (~15s interval)
let status;
do {
  await new Promise((r) => setTimeout(r, 15_000));
  status = await session.execute("codespar_shop", {
    action: "checkout_status",
    checkout_session_id: started.checkout_session_id,
  });
} while (status.status === "in_progress");
console.log(status.pix_copia_e_cola, status.total);

import time

# 1) search a store's catalog
found = session.execute("codespar_shop", {
    "action": "search",
    "merchant": "cobasi",
    "query": "ração golden 15kg",
})

# 2) START the store's real checkout — returns immediately, do not block
started = session.execute("codespar_shop", {
    "action": "checkout",
    "merchant": "cobasi",
    "items": [{"variant_id": found["offers"][0]["sku_id"], "quantity": 1}],
})

# 3) poll until the store's payable Pix is ready (~15s interval)
while True:
    time.sleep(15)
    status = session.execute("codespar_shop", {
        "action": "checkout_status",
        "checkout_session_id": started["checkout_session_id"],
    })
    if status["status"] != "in_progress":
        break
print(status["pix_copia_e_cola"], status["total"])

codespar_shop

codespar_shop

Actions

Stores

Direct execute

See also

On this page