> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Retailer accounts

> Choose whose retailer account the retail aggregate shops with: Agentcard's pooled accounts (default) or your own.

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  |

<Note>
  **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).
</Note>

## Instructions for your agent

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

```text Instructions for your agent theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>