Skip to main content
AgentcardClient is the class every buy tool and listener shares. The class exchanges your company’s client credentials for an access token, renews that token a minute before it expires, and sends purchase turns, conversation reads and Vault link requests to Agentcard. Build one and keep it for the life of your process.
agent.ts
The call returns one BuyTurn for the shopper user-42. Most apps never call buy themselves: buyTool calls it for the model. See Quickstart for the full wiring.

Create the client

Pass your company’s credentials, or one shopper’s own access token, and not both. The constructor throws a TypeError for any other combination.

Properties

Methods

bearer

Returns the access token the client sends: the shopper’s own, or your company’s, exchanged once and renewed a minute before it expires. Pass a company token that Agentcard refused to get a new one. The first call also sets sandbox.

buy

Sends one purchase turn and waits up to BUY_TURN_TIMEOUT_MS. Name the shopper once, with external_user_id or user_id, when you use company credentials, and leave both out under a shopper’s own token. The client sends a turn once, because a turn runs against live stores. The client sends again only after a 401, once, with a renewed token. After a timeout, unreachable or invalid_answer error, read the conversation with conversation before you send the turn again. Pass stream with onProgress, onCatalog, onAck or any of them together to ask Agentcard to stream the turn. A stream that breaks after the turn started returns a BuyTurn with error_code set to turn_timeout, so the caller reads the conversation for what the turn left.

conversation

Reads where one conversation stands: whether a turn is running, the last checkout, the orders it placed and the carts on the table. Pass who with company credentials. The call waits up to 30 seconds.

order

Reads where one placed order is now, by the order_id that order.placed carried. Pass who with company credentials. An order number two stores share throws order_id_ambiguous, with the stores in error.body.merchants; pass opts.merchant to say which. An order number Agentcard does not know throws order_not_found. See Read where an order is.

listCarts

Reads the shopper’s saved carts, newest first: what they carted at each store, the total each store last read, the chat each cart lives in (threadId), a short label and when it was started (createdAt). Pass threadId to read one chat’s carts alone. A page holds up to 20 carts; pass nextCursor as cursor for the next page, until it reads null. See Bring back a saved cart.

getCart

Reads one saved cart by the id listCarts named. Another shopper’s cart throws cart_not_found.

warmCart

Tells Agentcard the shopper came back to a chat with this cart, before they open it. The slow stores start reading at once, so the resumeCart that follows answers sooner. The call answers at once.

resumeCart

Reads every store’s total in a saved cart again and answers the cart with what changed at each store. Show the changes before the shopper approves. The call can take up to 90 seconds. A cart that was placed, dropped or ran out of time throws cart_ended. A change that reads needs_input with reason replace_account_cart waits on the shopper’s yes; call again with replace: [{ key: change.key, holds: change.holds.token }] once they give it.

bringCart

Pulls a saved cart into the chat threadId names: the cart moves there, never copies, and every store’s total is read again, as resumeCart reads it. Call it only when the shopper asks for a cart from another chat or picks one in your app. moved names the chat the cart came from, or reads null when it was already here. A cart whose payment is under way in another chat throws cart_paying, one that ended throws cart_ended, and one whose retail store, DoorDash or travel seller already has a cart of its own in this chat, such as a second Amazon cart, throws store_cart_here. See Pull a cart into this chat.

resumeCartAsText

Brings a saved cart back in a chat that shows text alone. send gets what the shopper saved at once, and what each store reads today once the resume answers. Answers the resume, which you pass to savedCartSettled for each cart.* event that follows.

setCartQuantity

Sets one item’s quantity in a store’s line, at the cart version you read. A quantity of 0 takes the item out. The store reads the line’s total again at the next resume; a Shopify store’s line reads failed with edited_waits_for_store until the shopper adds the item again. A line at a retail store, at DoorDash, or for a booking or a trip throws line_not_editable: the shopper changes it in their chat. A cart that moved past that version throws cart_changed, with the cart as it stands in error.body.cart.

removeCartStore

Takes one store’s whole line out of a saved cart, at the cart version you read. A cart left with no store ends. A line at a retail store, at DoorDash, or for a booking or a trip throws line_not_editable.

setCartDelivery

Sets a gift’s arrive-by day and note on the shopper’s cart. Nothing is priced or paid: each store’s delivery estimate is read against the day at the shopper’s next yes, and a line that arrives late is named before the approval. Throws gift_delivery_not_available until gift delivery reaches your company.
Returns the Vault link a shopper opens to connect to your company and add a card. Agentcard returns the link it already opened for that shopper while the link has time left, so a shopper who asks twice gets one link. The method needs company credentials and throws a TypeError under a shopper’s token. returnUrl is where the Vault page sends the shopper once their card is saved, such as your app’s own yourapp://agentcard-done. returnUrl must be one of the links your company registered. state comes back on that link unchanged, and a state without returnUrl throws a TypeError. See Checking out inside your app.

merchants

Reads one page of the merchants Agentcard buys at, each with the wallets that pay there. With company credentials and no who, you read each merchant as a shopper of your app reads it before signing in anywhere, so you can check a merchant before anyone connects. kind is direct, catalog or all, direct by default and all with q. q matches part of a name or domain. limit is 1 to 100, 50 by default. Pass the last page’s next_cursor as cursor. Each merchant’s wallets lists { wallet, status }, with wallet vault or link: The Vault reads at every merchant. Link reads at a store whose buys_through is browser, and for hotels, rental cars and flights booked through Agentcard. wallets is null from an older Agentcard.
Hands Agentcard the shopper’s Link grant, sealed to the key the confirm named, for a Link confirm that answered link_seal_needed. Only the sealed envelope leaves your server, and the call is POST /buy/v1/link-seals/{approval_id}. Pass who with company credentials. The answer is { status: 'sealed' }. The buy tool seals and posts for you; Pay with Stripe Link shows the steps over HTTP.

listen

Hears every event Agentcard sends your company over one connection your server opens. See listen.

delivered

Records that message reached the chat of the shopper you call externalUserId, so that shopper’s next buy.turn hands it to your model. listen and agentcardWebhook({ agentcard }) call it once onMessage returns, so call it yourself only for a message you delivered another way. The client keeps a message once per eventId, at most 20 messages per shopper, in this process’s memory.

answered

Records that your agent answers message with a turn of its own in the chat threadId names, so the shopper never reads its text there. For a message about one purchase, delivered skips the message from then on, and no later turn tells the model its text. A message about the shopper alone, such as a saved card, still reaches the next turn in the shopper’s other chats. Leave out threadId for a tool built without one. buy.nextStep calls it.

unanswered

Takes back answered for a message your agent’s turn could not answer. Pass the threadId you passed to answered. After you post the message’s text, delivered keeps it again. turn.release() calls it.

keptMessages

Returns the messages kept for this shopper in the chat threadId names, oldest first: each message about that chat’s purchase or about the shopper alone that reached the shopper’s chat, and that no history passed to turn.messages in that chat holds yet. Leave out threadId for a tool built without one: that tool gets the messages of the purchases made under no thread.

forgetMessages

Forgets these messages for this shopper in the chat threadId names. turn.messages calls it once the history it reads holds them. A message about the shopper alone stays kept for the shopper’s other chats until their own histories hold it.

Constants

BuyRequest

The body of one buy call. Every field is optional. BuyDeliveryAddress has the required fields street, city, state and zip, and the optional fields address2, phone, name, country and can_leave_at_door (boolean).

BuyTurn

One turn’s answer. Every field is present, and a field an older Agentcard does not send reads as null. BuyChoice has question (string or null), item (string or null, the item the choice is about), source and groups. source is menu_item for a restaurant item’s options, store_checkout for a store’s own size or colour question, and catalog_variant for a product’s sizes or colours in stock. Each group has name, required (boolean), min and max (max is null for no limit), and options. Each option has id (string or null, the option id the cart takes), label, and price_delta_cents (number or null, what choosing it adds to the price). BuyNextAction is one of shipping_details, guest_details, store_login, add_card, confirm, verification_code, approve or bank_challenge, in the order a purchase asks for them. bank_challenge comes after the approval, when the shopper’s bank asks them to approve the payment too, and the turn’s bank_challenge field carries the details.

BuySearchStatus

Every store a turn searched. searchAt(search, 'gap.com') returns the same block with only that store, matched by its id, its domain or its name. Each BuyMerchantStatus has merchant (the store’s id or domain), merchant_name, status, results, confirmed, first_result_ms (number or null) and ms. status is one of searching, confirmed, recently_confirmed, confirmation_unavailable, no_results, timed_out, failed or unavailable; Showing each store as it is searched says what each one means. A store with a status this version does not know is left out. merchantStatusLine(store, named) gives the line to show for one store, from merchants or from an onMerchantStatus update: still loading Walmart for an unavailable store the shopper named, and null for every other store. named is a store or a list of stores, each matched as searchAt matches it. searchStatusLines(search, named) gives every such line for the turn, in the order the searches started.

BuyCart

A cart as Agentcard answers it. Every amount is in the smallest unit of currency.

BuyCartLine

BuyCatalog

The products the last search found.

BuyCatalogItem

Show store.domain as where the product is sold. The field reads null when Agentcard knows no website for the store, such as a restaurant, and an older API leaves it out.

BuyPick, BuyStores and BuyStorePick

BuyConversation

Where one conversation stands. BuyLatestReply has message_id, text, messages (string[]), catalog (BuyCatalog or null, the products the reply showed) and created_at (string or null). BuyOrder has order_id (string or null), merchant, merchant_name, status, total_cents and placed_at (string or null). BuyOrder carries no merchant_of_record, who charged the shopper’s card: that field arrives on each order in raw.orders, and Send a dispute to the right place shows how to read it and what each of its fields says. For where one order is now, read it with order. BuyLastCheckout has at, merchant, merchant_name, status, code, message, order_id, decline_code, approval_url, approval_expires_at, placement_announced, approval_in_progress, add_card_url, add_card_expires_at and total_cents. All of its fields except at, merchant, merchant_name and status are null when absent.

Show a trip’s searches

When a shopper plans a trip, Agentcard asks where and when first, then searches flights, hotels and a rental car while the conversation goes on. Read the conversation and show each search as its results arrive:
conversation() returns the trip as it stands at that read. While any lane’s status is queued or searching, read the conversation again every few seconds and render the lanes again, and stop once none is. Right after the reply that sets the place and the dates, lanes can still be empty while the searches start, so keep reading until it lists a lane, then apply that rule. A waiting lane runs no search on its own: flights wait for the city the shopper leaves from. Read the conversation again after each reply, since a reply can start a waiting lane, and a change to the place, the dates or the party starts a new set of searches. BuyTrip has place, check_in, check_out, travelers, origin and lanes. The lanes come in the order a shopper reads them: flights first, since the flights set when the trip lands and leaves, then hotels, car, activities and payment, the check that the shopper’s card pays without stopping at checkout. Each lane has status, done, checking, results, items and decision. Until done is true, more results can still arrive, so show checking beside the lane, such as still checking hotels…, and never present its results as the full list. Once the lane is done, its status says how it ended: confirmed, no_results, failed, timed_out or cancelled. items holds up to 8 results, ordered by what the shopper said matters, such as the price or nonstop flights. Each result has product_id, title, price_cents, currency and fulfilled_by, the party the shopper books with, such as { "name": "Korean Air", "kind": "airline" }. Show fulfilled_by as one quiet line on the card, such as “via Korean Air”. decision says whether the shopper’s last preference re-ranked the results the lane held, searched again, or both, with the reasons. A hotels lane carries fits_flight, which is false when the flight the shopper picked lands on another day than the stay those hotels were searched for. Show the mismatch only when fits_flight === false: null means no flight is picked yet, which is no mismatch. The payment lane carries ready. Each of these can be null. A result whose fulfilled_by is null shows no seller line. A lane whose decision is null has had no preference stated, so show no decision.

BuyOrderStatus

Where one placed order is now, as order reads it. See Read where an order is for what each merchant answers.

BuyOrderShipment

One package of an order, as the carrier reports it. A value the carrier has not reported is null.

BuyOrderShippingAddress

The address a placed order ships or delivers to, as it was sent at placement.

Shopper

Who a call is for. Name the shopper exactly once with company credentials, and leave both fields out under a shopper’s own token.

AgentcardApiError

The error every refusal and failed call throws. AgentcardApiError extends Error. Through buy.answer, five refusals still answer the shopper: they come back as needs_input with the reason in reply and the code in error_code. They are cart_changed, nothing_to_confirm, conversation_closed, a delivery address that changed since the cart was built (a code that starts with delivery_address), and turn_in_progress. Every other refusal throws an AgentcardApiError.

Error codes

Agentcard refuses a conversation_id sent with the thread_id of another chat before it reads the message, so the other chat’s words never reach that purchase. The refusal comes back as a 409:
buyTool sends each purchase request once. Only a request that Agentcard refused with a 401 goes again, once, with a renewed token.