Retailer accounts

Orders on Agentcard Retail (Amazon, Walmart, Target, Best Buy and other major US retailers) are placed by our retail supplier. By default they run on pooled retailer accounts that we manage: you bring no credentials, nothing to set up, and retailer-side account risk stays on our side. You can instead register your own retailer account — per user, or one company account for your whole organization. Orders then land in that account: its order history, its Prime or loyalty benefits, its saved payment method.

	Pooled (default)	Your account
Setup	none	register once below
Order history	via Agentcard (`buy_track_order`)	in the retailer account
Prime / loyalty	no	yes, the account’s own
Credentials involved	none	stored by our retail supplier
Returns	routed through us	the account’s normal returns

How credentials are handled — the entire trade. Credentials (email, password, and the TOTP secret if the account has two-factor) are forwarded once to our retail supplier, which stores them to sign in and place orders. Agentcard never stores them and no API ever returns them. The TOTP secret is the long code behind “can’t scan the QR code?” in the retailer’s 2FA setup — it grants standing sign-in ability, not a one-time code. Register a dedicated or company account if that trade isn’t right for a personal one. Deleting the registration deletes the credentials at the supplier and reverts to pooled accounts immediately. Agents never collect these in chat — registration happens only on this API (or the dashboard).

Instructions for your agent

Paste this into your coding agent to add own-account retail ordering.

Instructions for your agent

You are letting this app's users (or the company) shop Agentcard Retail
(Amazon, Walmart, Target, ...) with their OWN retailer accounts instead of
Agentcard's pooled accounts. Implement server-side; base URL
https://api.agentcard.sh. Bearer: the registering user's connection
access_token; scope "org" needs an org-scoped session of an active org ADMIN
or OWNER (an ordinary member's session gets 403).

1. REGISTER (never collect credentials in chat — this API or dashboard only)
POST /buy/v1/retailer-accounts
{ "retailer": "amazon", "email": "...", "password": "...",
  "totp_seed": "<2FA secret — required when the account has 2FA>",
  "scope": "personal" }        // or "org" for one company-wide account
-> 201 { id, retailer, email_masked, has_totp }

2. USE IS AUTOMATIC
Orders at that retailer now use the account — no per-order flag. Precedence:
a user's personal registration wins over the org's company account. Payments
are unchanged: orders still ride the configured agentcard money path.

3. MANAGE
GET /buy/v1/retailer-accounts              -> masked list of registrations
DELETE /buy/v1/retailer-accounts/:id       -> revert to pooled accounts

Register an account

curl -X POST https://api.agentcard.sh/buy/v1/retailer-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retailer": "amazon",
    "email": "orders@yourcompany.com",
    "password": "…",
    "totp_seed": "JBSWY3DPEHPK3PXP",
    "scope": "org"
  }'

retailer — the store name as it appears in buy_search_stores (amazon, walmart, target, …).
totp_seed — required in practice for any account with two-factor enabled.
scope — personal (default) ties the account to the registering user + connection. org registers a company account shared by every user of your organization’s connections; it needs an org-scoped session belonging to an active org admin or owner — an ordinary member’s session is rejected with 403 (registering a company retailer account requires an org admin or owner).

Response:

{
  "id": "ral_…",
  "retailer": "amazon.com",
  "email_masked": "o…s@yourcompany.com",
  "has_totp": true
}

Use is automatic

Once registered, orders for that retailer use the account — no per-order flag. Precedence when both exist: the user’s personal registration wins over the org’s company account. GET /buy/v1/retailer-accounts lists what’s registered (masked); DELETE /buy/v1/retailer-accounts/:id reverts to pooled.

Own-account ordering is rolling out and may be briefly unavailable while our supplier deploys a fix on their side; registration always works, and orders fall back to pooled accounts until it’s active. Payments are unchanged: the order still rides the agentcard money path you’ve configured.

Getting Started

Authentication

Guides

Webhooks

Funding options

Withdrawals

MCP

Examples

Instructions for your agent

Register an account

Use is automatic

​Instructions for your agent

​Register an account

​Use is automatic

Instructions for your agent

Register an account

Use is automatic