Skip to main content
Conto Commerce lets your platform’s agents buy from online stores for your users. A purchase goes from a product URL and a task to a merchant-confirmed order under one purchase id. Your platform starts it and follows it with one organization API key. Conto shops, prepares checkout and pays with the buyer’s own card in the background. The buyer reviews every purchase and verifies their card on a Conto page. Your platform and your agents never receive card details. Test mode is open to every organization: start with the quickstart. Live purchases need Conto to enable them for your organization, and live cards need a Builder or Enterprise plan. The SDK methods here need an @conto_finance/sdk release that includes admin.purchasing.purchases. Amounts are positive integers in minor units with an uppercase currency: { amountMinor: 1200, currency: 'USD' } is $12.00. Purchases support USD only.

Credentials

Neither key can add a card, grant permission to shop or approve a purchase. Those happen on the buyer’s Conto page. An agent key also cannot create buyers or see another buyer’s purchases. A buyer’s card is paid only through purchases: conto.connectedCards.list() leaves it out and draw() refuses it.

Set up a buyer

Map one of your users to a buyer and send the buyer to the hosted setup page.
On the setup page the buyer confirms per-purchase and daily limits, adds a card in the card provider’s secure fields, and lets their agent shop with it. That creates a delegation. Read it with admin.purchasing.delegations.list(buyer.id). The buyer or your platform can revoke it. A delegation covers one card and the buyer’s limits. When the buyer changes their limits, the delegation is revoked and the buyer grants it again. Each purchase is still authorized for one merchant and one total, reviewed by the buyer and verified by the card. Hosted buyer-page POST requests (/api/purchasing/hosted/{action}) accept at most 32 KiB (32,768 bytes). The limit is enforced while reading the request, including when Content-Length is absent or understated. Oversized requests return HTTP 413 with RESPONSE_REJECTED before session exchange or buyer actions.

Inspect and revoke store allowances

When allowances are enabled, the buyer can grant spending authority for one store through the hosted review. Your platform can inspect and revoke these grants with an organization key; the SDK does not grant new authority.
Listing returns up to 50 records, newest first, including inactive grants. Each record identifies its store, status, expiration and limits. Reads require wallets:read; revocation requires wallets:create. These SDK methods require a release containing admin.purchasing.allowances. Revocation prevents subsequent credential release under the allowance; it does not undo a payment already submitted. Store allowances are not merchant-independent budgets. Live use remains separately gated pending provider verification.

Pay with a company card

If your platform pays for its users’ purchases and bills them itself, add one company card and let each buyer draw from it. Buyers then need no setup page, card or review of their own. You set two kinds of limits:
Each purchase still gets its own single-use authorization, for one store and one total. Purchases at or below the buyer’s reviewAboveMinor go ahead without a review. Above it, the purchase waits for your purchase_review answer (see Actions). A purchase over any of the buyer’s limits or the card’s caps is refused or ends unpaid with POLICY_DENIED, and limitReached says which: buyer_daily, buyer_monthly, buyer_daily_count, store or card_or_policy. Several buyers can buy at the same time. Company cards are test cards for now, and need Conto to enable them for your organization. A buyer with a card of their own cannot also use a company card.

Share what the buyer has at home

If your app knows what the buyer has in the kitchen, push it to Conto so the buyer’s agent can use it. Send the whole snapshot each time: inventory with a level per item, what the buyer usually buys, preferences, the recipes they picked to cook and the list they keep in your app.
Conto keeps the latest snapshot, encrypted, and returns it with getKitchenContext(). It is buyer data for the agent, never an instruction, and it changes no limit, card or purchase. Send no addresses, phone numbers, store credentials, card data or health diagnoses: text with markup, an email address or a long number is refused, and a snapshot over 128 KB is refused with status 413. clearKitchenContext() removes it. Set capturedAt to when your app read the kitchen, and updatedAt on a line when that item was counted earlier. A snapshot captured before the one Conto holds is refused with status 409 and KITCHEN_CONTEXT_OUT_OF_ORDER, so a late push never replaces a newer count. Sending the same capturedAt again replaces it, so retries are safe. For recipes, the agent doesn’t count an item past its expiresAt, or one counted more than 7 days ago, as on hand. It keeps that ingredient on the list and asks the buyer. What the buyer tells the agent in chat counts until a snapshot captured after it arrives. The agent never changes your snapshot. Kitchen context needs Conto to enable it for your organization. GET /api/purchasing/capabilities reports kitchenContext.available.

Start and follow a purchase

The purchase runs as the buyer’s agent. Without payment, Conto uses the buyer’s one delegation for this kind of store: a test card for a Conto test store, a live card otherwise. When the buyer has more than one, pass payment: { methodId, delegationId } from admin.purchasing.delegations.list(buyer.id). create() returns at once. Reusing the idempotency key with the same input returns the same purchase, so it is safe to retry after a lost response. A different input with the same key is refused with IDEMPOTENCY_CONFLICT. maxCost is the most the delivered order may cost. It narrows the delegation and never widens it. When you know the exact product, pass request.items with each URL, title, quantity and options. If your organization has store order checkout, a purchase with exact items uses it at stores that support it. Other purchases use browser checkout. Conto chooses once, when the purchase is created. Either way, answer the buyer_details form the purchase asks for. watch() yields every event in version order until the purchase ends. It streams server-sent events, reconnects from the last version, drops a duplicate after a reconnect, and falls back to polling where streaming is unavailable. Closing your process does not stop the purchase. Start watch() again with { after: lastVersion } to resume.

Grocery lists

For groceries, pass request.groceryList instead of items, with an Instacart store link as url. Conto searches the store for each item, adds it to the cart and checks out. It never substitutes a different product. If an item is unavailable or no product matches its requirements, an API order skips that item and continues with the matching items. The list builder records which items were added or skipped. If every item is unavailable, the purchase stops before payment with NO_ITEMS_AVAILABLE. A Grocery chat order instead pauses on a missing item so the shopper can answer in chat.
While the purchase runs, grocery reports progress at the store: When the store confirms the order, result has the store’s orderNumber, its receiptUrl and the amount charged, when the confirmation shows them. A list holds up to 20 items. A list at any other store is refused with MERCHANT_UNSUPPORTED. Live grocery purchases need Conto to enable them for your organization. In test mode, use Conto Test Grocery (see Test purchases).

From an agent’s own key

An agent that calls Conto itself, for example through the MCP server, uses its own SDK key. The purchase methods are the same:
Issue the key with admin.agents.createSdkKey(buyer.agentId, { name: 'Purchasing agent' }). It reaches that buyer’s purchases only.

Use a connected agent card from Claude Code or Codex

MCP 0.7.0 adds a separate owner-reviewed setup for an existing agent with a connected card. Call get_card_spending and get_card_purchase_setup, then propose enable_card_purchases with the masked card_id, per_purchase_minor and daily_minor in USD cents. The signed-in owner confirms the exact card and limits in Conto. This maps that same agent into the existing purchase runner without requiring a crypto wallet or creating a second agent. This flow refuses a conflicting buyer mapping, an in-flight card draw, inactive access, mixed test/live buyers and limits above the card assignment. It does not revive a revoked delegation or silently increase an existing buyer’s confirmed limits. Enabling checkout stops direct credential draws for that binding. Buyer review and cardholder verification remain required for purchases. After setup, read the masked methods from get_card_purchase_setup. Ask which card to use when several are eligible, and pass its paymentMethodId and delegationId with buyerId to purchase_start. For buyer/cardholder steps, call the setup tool with purchaseId to obtain an ownerReviewUrl. Only the exact setup owner, signed in to the matching organization with card-management permission, can continue through that entry to the existing secure buyer page. The owner authenticates in the browser; the navigation link grants no authority. Organization card-policy reviews still use their returned Inbox link. Externally managed buyers keep their application’s existing hosted-session flow. Use purchase_status for the outcome and list_card_activity for recorded card activity. Budget usage includes reservations; request completion and an executor report do not establish settlement. See MCP card tools for scopes, reporting windows and reviewed limit/revocation actions.

Status, phase and evidence

version increases by one with every visible change. paymentEvidence reports what is known about card authorization, the merchant’s confirmation and settlement separately. Evidence that is missing is unknown, never a guess. Settlement is always unknown here: the card provider reports issuance only.

Estimate and maximum

Once the store’s checkout is read, quote has the estimate (the store’s own total) and the maximum (the most the order can come to). Grocery orders can come to up to about 15% more than the estimate, for weighed items and refunds, so their maximum is above the estimate. For an exact total the two are the same. Every limit, maxCost and the card authorization are held to the maximum. The purchase is never paid above maxCost. Before the card is charged, an update with phase authorization or payment carries both, so you can tell the buyer “About $82, at most $94”. paymentEvidence.merchant.amount reports the amount charged. If the maximum is above maxCost, nothing is authorized. The purchase waits with a budget_increase action whose budget has the estimate, the maximum and the current maxCost. Answer it with a new maxCost that covers the maximum, or decline:
The answer applies at once. A new maxCost above what the buyer authorized for one purchase is refused with DELEGATION_INSUFFICIENT. Declining ends the purchase with OVER_BUDGET.

Actions

When status is awaiting_action, requiredAction says what is needed and who completes it. If the buyer saved their delivery details on Conto’s page, new purchases capture an encrypted copy when created. Conto uses that copy to answer the delivery form, and the buyer approves the details at review. Later profile edits apply to later purchases; purchases created before this behavior retain their previous profile lookup. Pass buyerProfileId: null when creating the purchase to answer it yourself. For the delivery form, phone accepts local digits, spaces, parentheses or dashes using the delivery country as its default. Include + and the calling code for an international number. Conto validates the number and normalizes it to E.164 before saving or forwarding it to checkout. Invalid numbers and extensions are refused; the store field’s formatting does not change the buyer’s number. Answer buyer_details with the fields the action lists for its form:
On a company card, answer the review with the total you saw, or decline it:
A review answer is saved before it is applied. It usually applies at once; if another worker is busy or the request is interrupted, the runner finishes it. An acknowledgment with status: "accepted" means application is still pending. If the total changed, approval is refused with RESPONSE_CONFLICT. A declined purchase ends with DECLINED_BY_ORGANIZATION. The buyer sees these details on the review page and approves them with the total. An identical answer again returns the same acknowledgment. A different answer to the same action is refused with RESPONSE_CONFLICT. An expired or replaced action is refused with ACTION_EXPIRED or ACTION_NOT_OPEN. Each action has an expiresAt. A purchase’s time starts when Conto starts shopping, not when you create it. Each new prepayment action extends a still-active response window to 14 minutes, capped by the purchase’s one-hour lifetime. Expired requests are not reopened. Prepayment shopping is capped at one hour from creation. Card authorization, scheduled purchases and payment reconciliation retain their existing windows. For the buyer’s actions, create a single-use link on your server and send the buyer there:
requiredAction.url points at the same Conto page. It opens only for a buyer who entered through a link your platform created, so it is safe to show. Conto also emails the buyer when a live purchase needs their review, card verification or a store sign-in, and again when the store confirms the order. Each email links to the step and works until the step expires. To reach buyers yourself, turn the emails off:

Store sign-in

At Instacart, your platform answers the buyer’s store sign-in. The action’s signin.step says what to send. Ask the buyer in your own app and pass the answer on. Conto enters it at the store and keeps neither the email nor the code. The answer is entered before the call returns. When Instacart confirms the sign-in, Conto requests a saved store session for up to 30 days when saved sign-in is enabled. Saving can fail or the store can expire its session sooner, so a later purchase may still require sign-in. If Instacart asks for an extra verification check, the purchase ends with STORE_VERIFICATION_REQUIRED. Start it again later.

Events and webhooks

A cursor ahead of the purchase returns CURSOR_INVALID. watch() handles it by yielding a purchase.resync event with the current purchase. Webhooks go to your organization’s webhook URL with the event type in X-Conto-Event and the event id in X-Conto-Delivery-Id. The id is the same on every retry, so deduplicate on it. Verify each delivery with the raw body:
It refuses a bad signature and a delivery older than five minutes.

Cancel

Before payment the purchase stops and cancellationOutcome is cancelled or requested. Once payment may have been submitted it is too_late and the purchase stays in reconciliation until its outcome is known. Cancelling never refunds or reverses a payment.

Errors

Refusals carry a stable code, a requestId and whether retrying the same request can succeed later.

Test purchases

Test mode is open to every organization. Create a setup link with environment: 'test'. The buyer adds a test card instead of a real one. A test card pays only Conto’s test stores and a live card never does: Conto Test Grocery takes request.groceryList and no product links. It finds each item by its query words and leaves out products with an exclude word. It ignores brand, size and unit. It sells bananas, organic bananas, Gala apples, strawberries, avocados, baby spinach, whole milk, large eggs, butter, cheddar cheese, Greek yogurt, whole wheat bread, spaghetti, white rice, chicken breast, ground coffee, orange juice and chocolate chip ice cream. It skips an item it does not sell and reports it, and a list with nothing it sells ends with NO_ITEMS_AVAILABLE. Like Test Supplies, it asks for delivery details. It delivers in a free standard window, quotes up to 15% over the estimate like a grocery store, and charges the estimate. A test purchase runs the same limits, policies, reviews and actions as a live one, and its authorization is recorded as simulated. No card network, card provider or store is involved, and nothing is charged.

Stop observing a purchase

Pass an AbortSignal or maxWaitMs to purchases.watch() to stop observation, including a stalled event stream. A zero timeout returns without opening a connection. Exiting the iterator also closes its event stream. Stopping observation does not cancel the purchase; use purchases.cancel(id) for that action.
An in-flight polling read may finish in the background after observation stops; its result is ignored. Reconnects are paced by pollIntervalMs (at least 500 ms) to avoid rapid retries when a stream closes immediately.