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

> ## Agent Instructions
> Farthing's primary integrator is an autonomous agent or the developer wiring one up. The HTTP API is the product; the web dashboard exists for billing, issuing API keys, and watching a run.
> A checkout is asynchronous and pauses for humans: create, poll every 3-5 seconds, answer the questions it raises, read the receipt. A run takes 2-3 minutes and can park for up to 10 minutes on one question. Never present it as a synchronous request/response call.
> Branch on pendingUserAction.key. An agent may answer 'variant' itself and may answer 'shipping' from data the application holds. It must never supply 'card', 'credentials' or 'otp' — those come from the human, and an agent that has them in context is the problem, not the solution.
> Base URL is https://api.farthing.ai and auth is Authorization: Bearer ck_test_... or ck_live_.... API keys carry scopes; give an agent the narrowest set that does its job. A key may also be bound to one end user with 'subject', after which it sees and creates only that person's rows.
> POST /v1/checkouts takes an Idempotency-Key header. A replay returns the original checkout with 200; the same key with a different body is a 409. Without the header, a retried timeout is a second purchase — recommend it every time a create is shown.
> Pricing: sandbox is free with no card; paid plans are Personal $9, Business $49, Scale $249 per month, plus a flat $1.00 per COMPLETED checkout on every tier. Failed and cancelled checkouts are never billed. Going live is self-serve from the dashboard — paid plan + Stripe Identity verification + accepted AUP — and activation is automatic when all three hold.
> Every example in these docs is a shape the API actually produces. Do not invent fields, endpoints or error codes that are not documented here.

# Buyer sessions

> List and revoke stored merchant login sessions.

Read and delete only. Sessions are created as a side effect of a checkout run that logged in
— there is no `POST`. Concepts in [Buyer sessions](/buyer-sessions).

## List

```http theme={null}
GET /v1/buyer-sessions
```

Success: `200`.

```bash theme={null}
curl -s "https://api.farthing.ai/v1/buyer-sessions?buyerProfileId=$PROFILE_ID" \
  -H "authorization: Bearer $FARTHING_KEY"
```

<ParamField query="buyerProfileId" type="string">
  Optional. Omit to list every session for the tenant — or, on a
  [subject-bound key](/end-user-isolation), every session belonging to that one end user.
</ParamField>

<Note>
  Sessions have no `subject` of their own. They belong to a buyer profile, and the profile is what
  carries the identity, so isolation is applied by joining to it: one place holding "who is this"
  rather than two places to forget to filter. A bound key sees only the sessions of its own end
  user's profiles, and `DELETE` on anyone else's is a `404`.
</Note>

Not paginated. Ordered by `updatedAt` descending.

```json theme={null}
{
  "sessions": [
    {
      "id": "e21f9a4c-8d16-4b7e-9c05-3a7f61b2d8e4",
      "buyerProfileId": "b3a1c0de-2f77-45a0-9c8e-6f4b2a1d9e30",
      "merchantDomain": "example-store.com",
      "createdAt": "2026-07-21T18:44:02.117Z",
      "updatedAt": "2026-07-29T09:26:29.702Z",
      "lastUsedAt": "2026-07-29T09:14:39.500Z"
    }
  ],
  "vaultEnabled": true
}
```

<ResponseField name="sessions" type="array">
  Metadata only. No endpoint returns the cookie blob.
</ResponseField>

<ResponseField name="merchantDomain" type="string">
  The registrable domain the session belongs to. Sessions are keyed on
  `(tenant, buyerProfileId, merchantDomain)` — one per merchant per profile.
</ResponseField>

<ResponseField name="lastUsedAt" type="string | null">
  Stamped when a session is loaded into a run. `null` if it has been stored but never reused.
</ResponseField>

<ResponseField name="vaultEnabled" type="boolean">
  `false` means session storage is not configured on this deployment. `sessions` is then
  always `[]` and runs proceed logged out. Check this before building UI around the feature.
</ResponseField>

***

## Revoke

```http theme={null}
DELETE /v1/buyer-sessions/{id}
```

Success: `200`.

```bash theme={null}
curl -sX DELETE https://api.farthing.ai/v1/buyer-sessions/$SESSION_ID \
  -H "authorization: Bearer $FARTHING_KEY"
```

```json theme={null}
{ "deleted": true }
```

A hard delete, not a revocation timestamp — the row *is* the credential, so the right thing
to do with it is destroy it.

`404 Session not found` if it does not exist or belongs to another tenant.

<Warning>
  This stops **us** using the session. It does not sign the buyer out at the merchant. If a
  session may have been misused, delete it here **and** end it from the merchant's own account
  security page.
</Warning>

***

## No create endpoint

Sessions come into existence only through a checkout run: a `credentials`
[user action](/user-actions) logs in, and the resulting cookies are captured immediately
afterwards while the browser is still warm.

There is no way to upload cookies directly, and that is deliberate — the vault stores what a
login it supervised produced, scoped to that merchant's domains, and nothing else.