---
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="Call · tools/call">

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

</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.
- **`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` \| `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` | What to search for, e.g. `tv 55 4k` |
| `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.