Skip to main content
A shopper who leaves a cart and comes back finds it waiting. Your app shows what they put in the cart at each store at once. Agentcard then reads every store’s price again, and the shopper sees which prices held, which changed and what sold out before they approve anything. Nothing is charged until the shopper says yes to the prices they read today. Agentcard saves a cart for every purchase your shoppers start, one cart per conversation, with a line for each store. A conversation is one purchase. You call nothing to save the cart.

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 a version, 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.
carts.ts
Pass 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.
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.
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.
When a store still pricing sends its total, text the shopper that store’s new total.
resumeCartAsText writes and sends both messages:
sms.ts
When a store still pricing settles, 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:
Your app can pull one too, from its own list. The cart moves rather than copying, so it can only be paid once, and the chat it left reads “This cart moved to another chat, and continues there.” A pulled cart takes everything with it, so the shopper’s yes in the new chat pays every store in it, Amazon, DoorDash and a flight included. A shopper who asks for one product of a saved cart, such as “get me those tumblers again”, gets only that product’s store. That store’s part moves to the chat they wrote in and is priced again, and every other store stays saved where it was. A store moves whole, with every product it holds there. To bring the rest, the shopper asks for the whole cart. A cart whose payment is under way in another chat stays there, and the pull is refused with 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.
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.
Build the buy tool with the cart’s id:
chat.ts
Leave 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.
carts.ts

Change a cart

Set one item’s quantity, or take a whole store out, at the cart version 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.
edit.ts
A refused change throws, and the cart as it stands is in 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 with cart_approving, and a chat where a purchase is still running refuses it with turn_in_progress. Send the change again once that ends.
gift.ts
Pass 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 reads changed 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.
change.handoff holds buyUrl, store, product, quantity, listedPrice and expiresAt:
resume.ts
resumeCartAsText tells the shopper so and asks them for no yes:
When your company registered a browser of its own for Agentcard to drive, the resume runs the store’s checkout again in that browser, and the line reads like any other store’s.

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’s expires_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.
  1. As a test shopper, ask for “a pack of AA batteries from amazon”, pick one, and stop at the cart’s total without approving.
  2. List the shopper’s carts. Check that the cart lists Amazon with the total you saw.
  3. Price the cart again. Check that Amazon’s change reads ready, changed, or needs_input with address_needed, and that the total before is the one you saw.
  4. Change the Amazon line with a version lower than the cart’s. Check that it is refused with cart_changed.
  5. Over the SDK or the API, pull the cart into a new chat id. Check that moved is set and the cart names the new chat.