@conto_finance/sdk 0.7.0 or later. 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 the buyer’s own card, grant permission to shop with it or approve a purchase on it. Those happen on the buyer’s Conto page. A company card is the exception: your platform adds it, assigns buyers to it and answers its reviews with the organization key. 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.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.
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. It cannot grant new ones. A later purchase skips review under a grant only when it holds no delivery details, or its delivery details are the buyer’s saved ones and match the purchase the buyer granted it on. Billing or store contact details, or any other address, send it to the buyer’s review.wallets:read scope and revocation needs wallets:write. These methods need SDK 0.7.0 or later.
Revoking stops new payments under the allowance but does not undo a payment already submitted. Live allowances need separate enablement, and capabilities() reports allowances.live.available. Repeat orders run on allowances and share their switch, reported as recurringPurchases in capabilities(). admin.purchasing.recurringPurchases has list(), get(), startCycle(), skipCycle() and cancel().
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: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
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: up to 10 items, each with a quantity of 1 to 10, and request.url set to the first item’s URL. 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 duplicates, and falls back to polling where streaming is unavailable. Pass signal or maxWaitMs to stop watching, and pollIntervalMs (at least 500 ms) to pace reconnects and polls. Stopping the watch or your process does not stop the purchase. Start watch() again with { after: lastVersion } to resume, and use purchases.cancel(id) to stop the purchase.
Grocery lists
For groceries, passrequest.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: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
An existing agent with a connected card can make these purchases over MCP once its owner confirms the card and limits in Conto. Buyer review and card verification still apply. See MCP connected-card tools forget_card_purchase_setup, the enable_card_purchases change the owner confirms, and purchase_start.
Status, phase and evidence
phase is queued, shopping, checkout, review, scheduled, authorization, payment, reconciliation, closed_unconfirmed or complete. 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 when it releases a card for the purchase, not when the charge settles.
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, and Shopify checkouts that show an estimated tax (quote.estimatedTax is true), can come to up to 15% more than the estimate, because the store sets the final charge after the order. Their maximum is the estimate plus 15%, so leave that margin in maxCost or expect a budget_increase. 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:
maxCost above what the buyer authorized for one purchase is refused with DELEGATION_INSUFFICIENT. Declining ends the purchase with OVER_BUDGET.
Actions
Whenstatus is awaiting_action, requiredAction says what is needed and who completes it.
If the buyer saved delivery details on Conto’s page, a new purchase keeps an encrypted copy, answers the delivery form with it, and shows it to the buyer at review. Later edits apply to later purchases. Pass
buyerProfileId: null when you create the purchase to answer the form 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:
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 gets 15 minutes once Conto starts shopping, and each new action before payment extends that window to at least 14 minutes from when it opens. Before payment, no purchase runs longer than one hour from when you created it. An expired action is not reopened.
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’ssignin.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. Plan for a sign-in on each purchase.
capabilities() lists saved_merchant_sessions as unsupported, and saved store sign-in is off unless Conto turns it on. 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 the URL set in Developers > Webhooks, signed with that page’s signing secret, with the event type in X-Conto-Event and the event id in X-Conto-Delivery-Id. Event types are purchase.created, purchase.updated, purchase.action_required and purchase.<status> when the purchase ends. The id is the same on every retry, so deduplicate on it. Verify each delivery with the raw body:
Cancel
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. A purchase that already ended returns already_final. Cancelling never refunds or reverses a payment.
Errors
Refusals carry a stablecode, a requestId and whether retrying the same request can succeed later.
Test purchases
Test mode is open to every organization. Create a setup link withenvironment: '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.