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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Quickstart

> Send a user's store session from your server and connect it to Agentcard.

Your company sends a store session it already holds for a user. Agentcard verifies it against the store, stores it encrypted for that user and your app, and returns a linked connection. The user does not open a consent page or enter a code for this import.

Send every call from your server with a production org token. DoorDash session imports are available to every production app in an active organization. The user must already have connected to your app through Agentcard. See [the Issuing quickstart](https://docs.agentcard.com/issuing/quickstart.md#1-get-your-credentials).

## 1. Create the connection

Send the user, store, and complete session your company holds. Each store's page defines its session format; see [DoorDash](https://docs.agentcard.com/commerce-sdk/connections/doordash.md). Agentcard refuses a dead or incomplete session before storing it. A `POST /buy/v2/connections` request with an incomplete session returns HTTP `400`:

```text title="Response · invalid session" theme={null}
{"error":"session_invalid","retryable":false}
```

Retry the create request below with the complete signed-in session from your integration.

```bash title="Request · create a connection" theme={null}
curl -X POST https://api.agentcard.sh/buy/v2/connections \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_7g8h9i",
    "merchant": "doordash",
    "session": { "…": "…" }
  }'
```

```json title="Response · 200 linked" theme={null}
{
  "object": "connection",
  "connection_id": "cxn_2b4d6f",
  "merchant": "doordash",
  "status": "linked",
  "last_verified_at": "2026-11-05T00:12:00Z"
}
```

If this user already connected DoorDash through your app’s hosted connect flow, an import for the same account replaces those credentials. A different account reference returns `account_mismatch`; disconnect the existing store connection first.

Agentcard now stores the session for this user, app, and store. Subsequent shopping calls through your app use it without resending the cookies. Agentcard never receives the store password through this endpoint, and neither the response nor the logs include the cookies.

## 2. Check the connection

```bash title="Request · check the connection" theme={null}
curl https://api.agentcard.sh/buy/v2/connections/cxn_2b4d6f \
  -H "Authorization: Bearer $ORG_TOKEN"
```

The status request returns the connection object above. `linked` means its stored session is available and has not expired; the store can still revoke a session before its recorded expiry. Only the app that created the connection can read or remove it.

## 3. Refresh the session

Send another `POST /buy/v2/connections` with the same user and store and the complete replacement session. For the same store account, Agentcard verifies and replaces the stored session, keeps the connection ID, and returns `200 linked`. A failed refresh leaves the existing session in place. To switch store accounts, disconnect first and create a new connection.

```bash title="Request · refresh the session" theme={null}
curl -X POST https://api.agentcard.sh/buy/v2/connections \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_7g8h9i",
    "merchant": "doordash",
    "session": { "…": "…" }
  }'
```

## 4. Disconnect

```bash title="Request · disconnect" theme={null}
curl -X DELETE https://api.agentcard.sh/buy/v2/connections/cxn_2b4d6f \
  -H "Authorization: Bearer $ORG_TOKEN"
```

`DELETE` returns `204` with no body, deletes the stored session, and clears the store connection and cached cart for this user and app. If store cleanup returns a retryable error, Agentcard has already removed the credentials; retry `DELETE` to finish cleanup before importing another session. A subsequent `GET` returns `disconnected`. The user can also remove store access from their Agentcard Vault.

## Look up fields and errors

| Field | Required | Notes |
| - | - | - |
| `user_id` | yes | The Agentcard user connected to your app. |
| `merchant` | yes | The store slug, such as `doordash`. DoorDash supports session imports. |
| `session` | yes | The complete signed-in session your company holds for this user. Shape is per store. |

| Status | Meaning |
| - | - |
| `linked` | Agentcard stores the verified session for your app. |
| `error` | The stored session expired. Refresh it with a valid session. |
| `disconnected` | The user or your app removed the connection. |

| Error | Meaning |
| - | - |
| `session_invalid` | The store did not accept the session. Submit a valid, complete session. |
| `session_sharing_unavailable` | Check the user's connection to your app, production token, organization status, and supported store. |
| `account_mismatch` | The replacement session names a different store account reference. Disconnect first. |
| `store_unavailable` | The store could not verify the session or finish disconnect cleanup. Retry the same request when `retryable` is `true`. |
| `session_expired` | Refresh the connection with a valid session for the same store account. |
| `connection_disconnecting` | Retry disconnect to finish clearing the previous store session before importing another one. |
| `connection_disconnected` | The user or your app removed the connection during import verification. Start a new import if access is still intended. |
| `connection_not_found` | Check the connection ID and use the credential for the app that created it. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.