code that names what went wrong. A refusal charges nothing, and the message says so whenever a payment was about to happen. Read code to decide what to do next. The wording of the message is written for you to read and can change, so never match on it.
A refusal is different from a declined purchase. A purchase Agentcard tried and could not finish is an answer, not an error: its status is declined, a decline_code says why, and reply explains it to the shopper. Read a declined answer covers those.
See how a refusal arrives
The codes are the same in the SDK, the MCP server and the API. Only the way a refusal reaches your code differs.- SDK
- MCP
- API
A call on The buy tool answers some refusals for the model instead of failing. A shopper not yet connected to your company comes back as
AgentcardClient, such as agentcard.conversation() or agentcard.order(), throws an AgentcardApiError:orders.ts
cart_changed, nothing_to_confirm, conversation_closed, a changed delivery address, cart_not_ready, turn_in_progress, pick_not_found and store_pick_not_found come back as status: 'needs_input', with the code in error_code and a reply that tells the model what to do:status: 'needs_card', with the link to add a card. Every other refusal fails the tool call: your model reads the message with its links taken out, and the error’s cause holds the AgentcardApiError.The client adds codes of its own, for a call that never got an answer it can read:On this page,
external_user_id is the externalUserId you pass, and conversation_id is the answer’s conversation_id.Find the code
Each code has its own section below, with the body as the API sends it. Two words recur: a conversation is one purchase, from the shopper’s first request to the order, and a cart’shash is a short code that names this exact cart at this price, which a confirm sends back.
A code your calls cannot cause never reaches you. A call that never sends
items or return_url, for example, never meets their refusals.
Name the shopper
Your company’s credentials buy for many shoppers, so every call says which one withexternal_user_id, your own id for that shopper. A call with no shopper is refused:
external_user_id alone, or user_id alone.
A call made with one shopper’s own access token that names another shopper is refused:
external_user_id that two shoppers carry is refused with both of them:
user_ids as user_id, and give each shopper their own id from then on.
Fix the request
A field missing or in the wrong shape is refused withinvalid_request, and error names the field:
pick as { "product_id": "..." }. Other values of error you can meet:
items is refused:
ask, such as "a 40 oz Stanley Quencher tumbler".
A delivery_address missing a part is refused:
street, city, state and zip, and country for an address outside the US.
A return_url, the page the shopper comes back to after a step, is refused unless your app registered it:
Continue the right conversation
Aconversation_id that is not this shopper’s is refused:
conversation_id to start a new one.
A conversation that has ended is refused:
thread_id, the id of a chat in your app, is refused under another:
conversation_id that chat’s own requests returned, or resume: true with this thread_id.
A pick of a product that is not in the conversation’s latest search is refused, and nothing is added:
store_pick_not_found the same way.
A pick of a product Agentcard can show but not buy is refused:
Confirm the cart that stands
A confirm names the cart the shopper said yes to. A confirm before any cart is refused:Pay at a store’s checkout
Some stores are bought through their own checkout page, which Agentcard fills in. The shopper pays there with the card saved in the Vault, Agentcard’s page where the shopper saves their card and approves a payment. A confirm of such a cart withoutpayment_source is refused:
"payment_source": "vault".
In the sandbox, a shopper with no test card saved is refused at the confirm:
supported_reason: "gate_refused", which means Agentcard cannot pay at its payment form, as Check where Agentcard can pay shows.
A store that cancels orders Agentcard places as a guest, without a store account, is refused:
Pay with Stripe Link
A shopper can pay with their Stripe Link wallet, as Pay with Stripe Link shows. A Link confirm missing a field is refused:conversation_id, and link_payment with its spend_request_id, amount_cents and currency.
A cart Link cannot pay is refused:
approval_id the confirm returned, with the same shopper’s external_user_id.
seal_by deadline the new confirm returns.
key_id.
Bring back a saved cart
A call that names a saved cart can be refused three ways:Find an order
A read of one placed order names it byorder_id. An order_id that is not this shopper’s is refused:
order_id the order.placed event carried, with the same shopper’s id.
An order number two stores share is refused with both stores:
merchant set to one of the listed stores.
Retry when Agentcard is busy
Agentcard answers one call at a time in each conversation. A call sent while the last one is still running waits, then is refused:turn_in_progress is false, then send the call again.
A short outage is refused, and nothing ran:
request_id if it keeps failing.
Read a declined answer
A purchase Agentcard tried and could not finish answers withstatus: "declined" and a decline_code. reply explains it to the shopper. A sandbox confirm declines this way on purpose:
Other values name the store’s own reason, such as a sold-out item. Show the shopper
reply, and send their answer as the next message.
- SDK
- MCP
- API
The buy tool reads two of these for you.
vault_approval_required arrives as status: 'approval_sent', and the approval link goes to sendLink. A shopper with no card arrives as status: 'needs_card', with the add-a-card link.