Know the three links
A purchase needs a link at three moments:
Every answer names the one step the shopper takes next in
next_action. Agentcard asks for one step at a time, in the order of this table:
A shopper who still has a card to save and a store to sign in to hears about the sign-in first, and the card second.
Find each link in an answer
Each link comes with the moment it stops working, as an ISO 8601 date and time such as2026-11-19T21:14:12.178Z. A store sign-in link also names its store, so your button can read “Sign in to DoorDash”.
- SDK
- MCP
- API
Pass
sendLink to buy.turn, the call that runs the buy tool for one shopper message. The tool hands sendLink each link and waits for it, so the shopper holds the link before your model answers.chat.ts
expiresAt is null when Agentcard did not say. Without sendLink, read the same links from turn.links or from the onResult callback.Send each link as it is
Send each URL exactly as Agentcard gave it, alone in its own message or behind one button. An approval or add-a-card link with anything added to it no longer works, and the shopper lands on the Vault’s sign-in page instead of the step. Never let your language model retype a link. A model that copies a URL into its answer can change one character and break it. Name each link by what it is for instead: the link to add a card, to sign in to the store, or to approve the payment. In a text chat such as SMS or iMessage, send the sentence that asks for the step first, then the URL alone in the next message. iMessage shows a URL that stands alone as a preview card, and it breaks one with words attached.- SDK
- MCP
- API
Your model never reads a link. A tool runner puts each tool answer straight into the model’s context, so the tool hands each link to your code and the model reads only
link_sent: true. The model’s description tells it never to write a link.With onItem on the turn, the turn holds each step link until the message that asks for it went out, then sends the link right after it. A held link also goes out when the turn’s next call starts, or after 20 seconds, so a model that writes nothing still sends it. Answer each message shows onItem.A sendLink that throws on a Vault or approval link makes the call throw, and the model never reads that a link went out. Catch the error, tell the shopper something went wrong, and let them ask again. A link your sendLink throws on stays out of turn.links.Send the store sign-in link
A store such as DoorDash places an order only on the shopper’s own account. When the shopper reaches checkout there, the answer readsnext_action: "store_login" and carries a sign-in link named for the store. The shopper signs in on the store’s page, comes back to the chat, and the purchase moves on without them typing “done”, as Move the purchase on shows.
A shopper can hold sign-in links for two stores at once, each with its own cart. Each link and each message about a sign-in names its store, so match them by store before you mark a sign-in as done.
A store that prices the order only once it is in the shopper’s own account answers with a total marked as an estimate. DoorDash is one. Show that total as an estimate, such as “about $15.73 before tax and delivery”.
- SDK
- MCP
- API
The link reaches
sendLink with kind: 'store_login' and the store’s name in store. The cart reads totalIsEstimate: true, and the model reads total_is_estimate and total_leaves_out, so it says the total is before those costs.Send a link again
When the shopper asks for the link again, pass their words on as a new message in the same chat. While a link still has time left, Agentcard answers with the same link, so the shopper never has two links for one step. An expired link is replaced with a new one. Agentcard also reminds the shopper on its own:approval_expiring and card_link_unfinished messages carry the link again in their text, ready to post. These reminders leave the step open.
- SDK
- MCP
- API
The model calls the tool again, and the tool hands the same link to
sendLink again. The reminders arrive through listen or the webhook handler.Open each step in a pop-up
On the web, open each step in a pop-up window over the chat, so the shopper never leaves it, and close the pop-up when the message that ends the step arrives.- SDK
- MCP
- API
actionWindows from @agent-cards/commerce-sdk/browser opens a step in a pop-up centered over the chat and closes it when the step ends. The browser entry imports no Node module, so any bundler takes it.chat-ui.ts
id, such as vault_1x9k2qd, the same every time the same link is handed over, with no part of the URL in it. Use it as a DOM key or in a log. actionLinkId(link) reads the id from a link that has none.settle closes each open pop-up whose step the message ends and returns [{ step, outcome }]. A pop-up the shopper closes before the step ends reaches onClosed, checked every 500 milliseconds. The step is still open, so keep its link on screen, and a tap opens it again. A tap on a step whose pop-up is open brings that window to the front.The pop-up is 480 by 760 pixels by default. Pass width and height to change it. A phone’s browser opens the pop-up as a tab, and settle closes that tab the same way. dispose() stops watching and leaves every pop-up open, so a chat that remounts never shuts the page where a shopper is typing a card.open opens only an absolute https: page, and a store sign-in only on agentcard.sh, agentcard.com and their subdomains. For any other link it throws ActionLinkRefusedError and opens nothing. A chat on a local stack that opens its http://localhost Vault link logs:The buy tool never hands over a link
open refuses, so a refusal means your code built or changed the link.Know when a step ends
Each step ends with a message from Agentcard whosekind says how:
Once a step ends, take its button off the screen. An approval is done once the shopper approved, even when the order then failed or the payment was refused, because the approval page has nothing more to do. The message’s
text tells the shopper what happened. After store_connect_failed or store_connect_expired, text offers a new sign-in link, so post it as it is.
A message about another store leaves a step open: a store_connected for DoorDash never ends a sign-in to Locale that the shopper has open beside it. A message that names a different approval or add-a-card link leaves this link’s step open too. Message types lists every kind.
- SDK
- MCP
- API
actionLinkOutcome(link, message) returns how a message ended the step, completed, declined, failed or expired, or null when it left the step open. It compares the store in the link with facts.merchantName, and the link with facts.approvalUrl or facts.cardLinkUrl. ACTION_LINK_ENDINGS holds the whole table.Check it in the sandbox
The sandbox is Agentcard’s test mode: it searches real stores, charges nothing and stops before payment.- As a new test shopper, send
a chicken burrito from chipotle on doordash, pick the options, and say “lets checkout”. Check that a store sign-in link arrives, named for DoorDash. - Ask for the link again. Check that it is the same link.
- Search your model’s replies for
https://. Check that none is there.
- SDK
- MCP
- API
- Send “two packs of AA batteries from Amazon” as a test shopper who has no card. Check that
sendLinkreceives avaultlink and that the model’s reply says a link is waiting, without containing it. - Open the link in a pop-up, then close the pop-up before you finish. Check that
onClosedfires and the link stays on screen.
card_added, store_connected or approval_declined message, and it places no order, so check the endings and the approval link with live credentials by buying one inexpensive item with your own card, as Approving a purchase shows.