Quickstart

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. Agentcard must enable store connections for your app, and the user must already have connected to your app through Agentcard. See the Issuing quickstart.

1. Create the connection

Send the user, store, and complete session your company holds. Each store’s page defines its session format; see DoorDash. Agentcard refuses a dead or incomplete session before storing it. A POST /buy/v2/connections request with an incomplete session returns HTTP 400:

Response · invalid session

{"error":"session_invalid","retryable":false}

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

Request · create a connection

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": { "…": "…" }
  }'

Response · 200 linked

{
  "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

Request · check the connection

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.

Request · refresh the session

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

Request · disconnect

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`. Your app must have access to the store.
`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, and enabled stores.
`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.

Getting started

Guides

Vault

Issuing

Commerce SDK

Partners

1. Create the connection

2. Check the connection

3. Refresh the session

4. Disconnect

Look up fields and errors

​1. Create the connection

​2. Check the connection

​3. Refresh the session

​4. Disconnect

​Look up fields and errors

1. Create the connection

2. Check the connection

3. Refresh the session

4. Disconnect

Look up fields and errors