---
title: codespar_shop
description: Buy-side shopping. Act as the shopper, search a store's live catalog and buy, minting the store's real Pix copia-e-cola to settle from the governed wallet. VTEX guest checkout and Mercado Livre.
---

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

<MetaToolHeader tool="codespar_shop" />

The agent is the shopper. Use [`codespar_checkout`](/docs/concepts/meta-tools/checkout) when you are the merchant creating a checkout for a shopper to pay you.

## Actions

<MetaToolActions tool="codespar_shop" />

## Example

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

<Split min={380}>
<SplitPane label="The same call, four ways">

<Tabs items={["MCP", "TypeScript", "Python", "CLI"]}>
<Tab value="MCP">

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

</Tab>
<Tab value="TypeScript">

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

</Tab>
<Tab value="Python">

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

</Tab>
<Tab value="CLI">

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

</Tab>
</Tabs>

</SplitPane>
<SplitPane label="Result · fields the tool document names">

```json title="result"
{
  "checkout_session_id": "cks_0000",
  "status": "in_progress"
}
```

</SplitPane>
</Split>

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`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/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

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | No | `search` \| `research` \| `checkout` \| `checkout_status`. Defaults to `search`, and an unknown value also becomes `search` (see the Actions table). |
| `merchant` | `string` | For `search`, `checkout` | Store slug: `cobasi` \| `animale` \| `lojaspompeia` (VTEX), `meli` (Mercado Livre) |
| `query` | `string` | For `search`, `research` | What to search for, e.g. `tv 55 4k`; for `research`, the open request, e.g. `fone bluetooth` |
| `criteria` | `object` | No | `research` only, all optional: `priority` (`total` or `eta`), `max_total_minor` (centavos, shipping included), `sources` (`registry`, `vtex`, `meli`), `limit` (offers per source, 1..5) |
| `limit` | `number` | No | Max results, 1..20 (`search`) |
| `items` | `array` | For `checkout` (VTEX) | `[{ variant_id, quantity, seller? }]`, with `variant_id` = the offer's `sku_id` |
| `url` | `string` | For `checkout` (Mercado Livre) | Listing URL to buy; Mercado Livre has no buyer API |
| `paymentMethod` | `string` | No | Settlement rail the store mints: `pix` (default) |
| `consumer_id` | `string` | No | Which buyer is shopping; resolves their connected Mercado Livre login and, with `auto_pay`, whose wallet pays |
| `checkout_session_id` | `string` | For `checkout_status` | From `checkout` |
| `auto_pay` | `boolean` | No | `checkout_status` only: when the order is `ready_for_payment`, pay it server-side from the consumer's governed wallet (pass `consumer_id`) and return `status: "paid"` plus a payment receipt |
| `buyer` | `object` | No | Vaulted shopper profile (email, firstName, lastName, document, phone) |
| `address` | `object` | No | Shipping address (postalCode, street, number, neighborhood, city, state, complement) |

## Errors and what to do

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

| `reason_code` | Meaning | What to do |
|---|---|---|
| `store_temporarily_unavailable`, `checkout_failed` (`retriable: true`) | A temporary store or session fault, not an out-of-stock. | Call `checkout` again. |
| `no_shipping` | The only genuine no-delivery / out-of-stock. | Offer alternatives from `search`. |
| `identity_required` | The store demands a login the agent cannot pass. `reason_hint` says whether a fresh guest email can work or the store requires a login for every purchase. | Try a dedicated checkout email not registered at the store, or stop retrying when the hint says login is mandatory. |
| `not_connected` | Mercado Livre: the buyer's login is not connected. | `codespar_manage_connections` `connect_start` / `connect_finish`, then retry. |

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](/docs/concepts/directed-pay) server-side. On Mercado Livre the purchase is on the buyer's own account, through the login they connected once.

## Related

- [`codespar_pay`](/docs/concepts/meta-tools/pay): settle the minted Pix by `checkout_session_id`
- [`codespar_wallet`](/docs/concepts/meta-tools/wallet): the balance the purchase is paid from
- [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections): vault the shopper's identity, or connect a login-walled store
- [`codespar_checkout`](/docs/concepts/meta-tools/checkout): sell-side, the merchant creating a checkout for a shopper
- [Shopper identity](/docs/concepts/shopper-identity): what `save_profile` vaults and why the email matters
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout): 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.