codespar_shop

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.

Buy-sideYour agent is the spender: money leaves the wallet it governs, under a signed mandate.

Search and buy from real stores; async checkout session to the store's payable Pix.

tool codespar_shop3 actions1 canalways required action

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

Actions

`action`	What it does	Money	Needs
`search`	Search a store's live, buyable catalog; each offer carries product_id, sku_id (the checkout variant_id), price and variants	no	`merchantquery`
`checkout` example below	Start the store's real checkout and return at once with checkout_session_id and status in_progress; do not block	no	`merchantitems`or`url`
`checkout_status`	Poll a checkout session until ready_for_payment returns the payable Pix; with auto_pay it pays from the wallet	can move money	`checkout_session_id`

Unknown action: falls back to `search` instead of refusing. A misspelt `checkout` searches the catalog and returns offers, with no error. Measured 2026-09-09.

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

Example

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

Call · tools/call

arguments

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

Result · fields the tool document names

result

{
  "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.
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

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 server-side. On Mercado Livre the purchase is on the buyer's own account, through the login they connected once.

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.

On this page