---
title: codespar_shop
description: 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().
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

# codespar_shop

<Callout title="Meta-tool" type="info">
`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`](/docs/concepts/meta-tools/pay) × pix). Use [`codespar_checkout`](/docs/concepts/meta-tools/checkout) when you are the merchant creating a checkout for a shopper to pay you.
</Callout>

## 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`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/pay) using `method: "pix"`.

## Direct execute

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

<Tabs items={["TypeScript", "Python"]}>

```ts tab="TypeScript"
// 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);
```

```python tab="Python"
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"])
```

</Tabs>

## See also

- [codespar_checkout](/docs/concepts/meta-tools/checkout) — sell-side: create a merchant checkout for a shopper to pay you
- [codespar_manage_connections](/docs/concepts/meta-tools/manage-connections) — vault the shopper's checkout identity / connect login-walled stores
- [codespar_pay](/docs/concepts/meta-tools/pay) — settle the minted Pix
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout) — cart → checkout → fulfillment
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list