Skip to main content
Make your first purchase for a shopper with plain web requests, from any programming language. This page takes you from your company’s credentials to a confirmed cart, with test credentials that search real stores and never charge a card. Every request goes to 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:
The sandbox is Agentcard’s test mode: it runs everything against real stores and charges nothing. 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 your client_id and client_secret for an access token, a short-lived key you send with every request:
Send it as 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 as ask, 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.
The answer carries 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 as ask and the product’s ref as pick.product_id:

Confirm the cart

The answer now carries a cart block with the lines, the fees and the total. Show the shopper the cart from this block, an excerpt here:
The cart’s 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:
Agentcard charges only for the cart the shopper saw. When the shopper still has a step to take, such as saving a card or approving the payment on their phone, the answer carries a link for them, and Send each link shows how to hand it over.

Check the test run

With test credentials, the confirm stops before the card reaches the store and answers with decline_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