List the shopper’s carts
Read the shopper’s carts when they come back. The newest comes first, and a page holds up to 20. Each cart holds its lines, one per store. A line carries the store’s name, the items, the quantities, the choices the shopper made such as a size, and the total that store last read. Show the cart from these fields at once, before any store is read again, so the shopper never waits on an empty screen. Each cart also carries aversion, a number that goes up each time the cart changes, which you send back when you change the cart.
Pass your own id for a chat to read only that chat’s carts.
- SDK
- MCP
- API
carts.ts
threadId to read one chat’s carts alone, and pass nextCursor as cursor for the next page. Read one cart by its id with getCart(cartId, who).Price every store again
Ask Agentcard to read every store’s total again when the shopper opens the cart. This step is called a resume, since it brings the cart back. The answer holds the cart as it stands now and one change per store, with the total the shopper last saw and the total the store reads now.
A change’s reason says more about some of them:
A resume can take up to 90 seconds when a store’s own checkout runs again. A store still pricing when the resume answers reads
checking, and its total arrives later, as Hear a late price shows.
When the shopper’s own DoorDash cart already holds another meal, the change reads needs_input with replace_account_cart. Its holds field names what that DoorDash cart holds now, with a token that names exactly that cart. Ask the shopper whether to replace it, and on their yes resume again with the line and that token. A DoorDash cart that changed since the question is asked about again, never cleared.
- SDK
- MCP
- API
resume.ts
resumed.cart is the cart now, and each change in resumed.changes carries outcome, reason, beforeCents and nowCents. To replace the shopper’s DoorDash cart on their yes:resume.ts
Hear a late price
A store that answers after the resume sends its total on its own:cart.line_checking while it prices, then cart.line_ready, cart.line_changed, cart.line_unavailable or cart.line_needs_input. cart.ready follows once every store has given its own total. Change that store’s line in your chat when its total lands.
- SDK
- MCP
- API
Read each event with
cartEventOf, from agentcard.listen or your webhook handler, and match it to the cart and the store’s line.Text it in a chat
In a chat that shows text alone, such as SMS or iMessage, send the shopper two messages: what they saved, at once, and what each store reads today, once the resume answers.- SDK
- MCP
- API
resumeCartAsText writes and sends both messages:sms.ts
savedCartSettled writes its text. Pass the same resumed for every event of that resume:events.ts
Pull a cart into this chat
A new chat starts with no cart. A cart only moves to another chat when the shopper pulls it, so nothing they saved in a private chat shows up in a group on its own. The shopper can pull a cart by asking in their own words, such as “bring back my cart from earlier”. Agentcard lists their carts from other chats, and the one they pick moves to the chat they wrote in and is priced again:cart_paying. Let the payment finish in that chat. A chat that already holds its own cart with the same seller refuses the pull with store_cart_here: a second Amazon or Walmart cart, a second DoorDash cart, or a second flight, hotel or booking with the same seller. The shopper finishes or clears the cart in this chat first, or keeps the saved one in its own chat. A store whose checkout Agentcard fills in itself, such as a Shopify store, holds a cart in each chat, so two of its carts can share one chat.
- SDK
- MCP
- API
carts.ts
resumed.moved names the chat the cart came from, or reads null when it was already here. A refused pull throws:Send the yes to the cart
Send the shopper’s next message to the saved cart, so their words and their yes go to it. Agentcard answers with the cart as it stands now, says what changed since the shopper saved it, and asks for a yes at that price. The shopper’s yes then confirms that cart, as any purchase does. Stop sending the cart’s id once no saved cart is open.- SDK
- MCP
- API
Build the buy tool with the cart’s id:Leave
chat.ts
cartId out once no saved cart is open.Start the price check early
Tell Agentcard the shopper came back as soon as they open the chat, before they open the cart. The slow stores start pricing then, so the resume answers sooner.- SDK
- MCP
- API
carts.ts
Change a cart
Set one item’s quantity, or take a whole store out, at the cartversion you read. Each change answers the cart with its new version. A quantity of 0 takes the item out, and a cart left with no store ends. Change a cart only when the shopper asked.
A change reaches a store whose checkout Agentcard fills in itself, and most such stores price the changed line again at the next resume. A Shopify store’s line comes back failed with edited_waits_for_store, since its checkout still holds the old count: the shopper adds the item again at the new count.
A line at a large store such as Amazon, Walmart or Target, at DoorDash, or for a flight, a hotel, a car, a table or tickets follows the shopper’s own cart at that seller, so the change is refused with line_not_editable. The shopper makes that change by asking in their chat.
A change sent with an older version is refused with cart_changed, and the cart as it stands comes back with the refusal. Show the shopper that cart, and send their change again with its version.
- SDK
- MCP
- API
edit.ts
error.body.cart:Set a gift’s arrival day
Set the latest day every line should arrive by, and a gift note of up to 240 characters. Nothing is priced or paid. At the shopper’s next yes, each store’s own delivery estimate is read against the day: a line that arrives late is named before the approval and left out of it, unless the shopper keeps it anyway. A new day clears the late lines the shopper kept. A cart being approved or paid refuses the change withcart_approving, and a chat where a purchase is still running refuses it with turn_in_progress. Send the change again once that ends.
- SDK
- MCP
- API
gift.ts
keepLate with the keys of late lines the shopper keeps, and null to clear the day or the note. The answer carries the cart’s new version.Hand a store to your agent
When your company’s own agent checks out at a store instead of Agentcard, Agentcard never reaches that store’s checkout. A resumed line for such a store readschanged with reason listed_price: the new total is the price the store lists, before tax and shipping. The line reads that way even when the price did not move, because only your agent’s checkout reads the store’s total.
The change carries handoff, a new link your agent opens to buy, like the one it got for the first purchase. It names the store, the product, how many to buy, the listed price of one, and when the link stops working for this purchase.
The shopper approves the store’s real total when your agent’s checkout reaches payment. A product the store no longer lists reads unavailable with offer_gone, and carries no link.
- SDK
- MCP
- API
change.handoff holds buyUrl, store, product, quantity, listedPrice and expiresAt:resume.ts
resumeCartAsText tells the shopper so and asks them for no yes:Know how long a cart lasts
A cart lasts as long as its longest-lived store line, counted from that store’s last price. The cart’sexpires_at says when.
A cart that ran out of time, was placed or was dropped leaves the list, and a resume of it is refused with
cart_ended.
Check it in the sandbox
The sandbox is Agentcard’s test mode, which charges nothing.- As a test shopper, ask for “a pack of AA batteries from amazon”, pick one, and stop at the cart’s total without approving.
- List the shopper’s carts. Check that the cart lists Amazon with the total you saw.
- Price the cart again. Check that Amazon’s change reads
ready,changed, orneeds_inputwithaddress_needed, and that the total before is the one you saw. - Change the Amazon line with a
versionlower than the cart’s. Check that it is refused withcart_changed. - Over the SDK or the API, pull the cart into a new chat id. Check that
movedis set and the cart names the new chat.