https://api.agentcard.sh. If your agent runs in TypeScript, the Commerce SDK makes these same requests for you.
Get your test credentials
Credentials come from the Agentcard CLI, a command-line tool that installs nothing in your project. Sign in, where a new email creates your account, then copy your sandbox credentials:credentials asks your company’s name the first time and copies a client_id and a client_secret to your clipboard.
Get an access token
Trade yourclient_id and client_secret for an access token, a short-lived key you send with every request:
Authorization: Bearer <access_token> on every request below, and ask for a new one after an hour. sandbox: true confirms the token comes from test credentials.
Send what the shopper asked for
Send the shopper’s words asask, and your own id for the shopper as external_user_id on every request. Agentcard keeps each shopper’s purchases, saved cards and addresses under that id.
reply, the text to show the shopper, a catalog block with the products Agentcard found, and a conversation_id, the id of this purchase. Send the conversation_id back on every later request about the same purchase:
status: needs_input means Agentcard needs something from the shopper. Show them reply and the products, and send their answer with the same conversation_id.
Pick a product
When the shopper picks one, send their words asask and the product’s ref as pick.product_id:
Confirm the cart
The answer now carries acart block with the lines, the fees and the total. Show the shopper the cart from this block, an excerpt here:
hash is a short code that stands for this exact cart: these products, these prices, this total. When the shopper says yes, send it back as confirm:
Check the test run
With test credentials, the confirm stops before the card reaches the store and answers withdecline_code: sandbox_mode. That answer means the test passed: the search, the cart and the approval worked as they do live, and nothing was charged. Swap in your live credentials to place real orders.
Keep going
- Show products and show the cart
- Send each link and take the next step
- Check where Agentcard can pay
- Test in the sandbox and read a refusal
- Bring back a saved cart and pay with Stripe Link
- Create an access token, the token request in full