> ## 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.

# Usage

> Completed checkouts by day, and gross merchandise volume by currency.

## Get usage

```http theme={null}
GET /v1/usage
```

Success: `200`.

```bash theme={null}
curl -s "https://api.farthing.ai/v1/usage?from=2026-07-01&to=2026-08-01" \
  -H "authorization: Bearer $FARTHING_KEY"
```

### Query

<ParamField query="from" type="string" default="start of the current UTC month">
  Any string `Date` can parse — `2026-07-01` or a full ISO timestamp. Inclusive.
</ParamField>

<ParamField query="to" type="string" default="now">
  Same format. **Exclusive**, so `to=2026-08-01` covers July completely without bleeding into
  August.
</ParamField>

The default window is the current calendar month, which is the unit tenants are billed in.

### Response

```json theme={null}
{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "completedCheckouts": 148,
  "byDay": [
    { "day": "2026-07-27", "count": 12 },
    { "day": "2026-07-28", "count": 31 },
    { "day": "2026-07-29", "count": 9 }
  ],
  "merchandiseVolume": [
    { "currency": "USD", "amount": "4210.55" },
    { "currency": "GBP", "amount": "318.00" }
  ]
}
```

<ResponseField name="from" type="string">The resolved window start, echoed as ISO 8601.</ResponseField>
<ResponseField name="to" type="string">The resolved window end, exclusive.</ResponseField>

<ResponseField name="completedCheckouts" type="integer">
  **This is the billable number.** One per checkout that reached `succeeded`.
</ResponseField>

<ResponseField name="byDay" type="array">
  `{ day, count }` with `day` as `YYYY-MM-DD`. Days with no completions are **omitted**, not
  zero-filled — fill gaps yourself if you are drawing a chart.

  **The buckets are UTC days**, cut at UTC midnight, matching `from`, `to` and every other timestamp
  the API returns. They do not follow your timezone or ours: a checkout that completed at 02:00 UTC
  belongs to that UTC day everywhere, so the same window always returns the same buckets.
</ResponseField>

<ResponseField name="merchandiseVolume" type="array">
  `{ currency, amount }` — the sum of receipt totals, grouped by currency. Reporting only; we
  bill per completed checkout, not a percentage. Currencies are never converted or combined.

  Checkouts whose receipt carried no total are excluded from this sum but still counted in
  `completedCheckouts`, so the two will not always reconcile.
</ResponseField>

### Errors

| Status | Message                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | `Invalid from/to date` — a value `Date` could not parse                                                                 |
| `400`  | `'from' must be before 'to'` — an inverted range is a caller bug, and answering it with a cheerful zero would hide that |

## What is metered, and why

We meter **completed** checkouts. Never attempts.

Metering attempts would mean earning more when the agent fails, which is exactly backwards
for a product whose entire problem is reliability. Billing on completion puts our revenue and
your success on the same side.

Practically: a checkout that ends `failed` or `cancelled` costs you nothing, however far it
got and however many browser-minutes it burned. A run that reached the payment step and had
its card action declined is free. Only an order that confirmed is billable.

<Note>
  The usage record is written at the single point a checkout becomes successful, and is unique
  per checkout, so an orchestrator replay can never double-bill. Numbers here should reconcile
  exactly against your own count of `succeeded` checkouts.
</Note>