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

# Billing and statements

> Monthly statements, signed contract terms, invoices and receipt disputes.

Admins see each month's statement, invoices and disputes under **Billing**. Members receive `403 insufficient_org_role`; agent tokens are refused.

![Billing page for September 2026 with opening balance, credits in, spent and closing balance, and a table of credit lines by agent and source](https://mintcdn.com/freebutter/NxHVpA9fr_Nv_dvm/images/console/billing.webp?fit=max\&auto=format\&n=NxHVpA9fr_Nv_dvm\&q=85\&s=1da16151579ad28390076d409733cbc0)

Billing: the month's balances, credits added and spend.

## Download a statement

**1. Pick the month**

Open **Billing** and choose a UTC month.

**2. Download**

**Download CSV** saves it; **Print** gives a paper copy.

## Contracts and invoices

Contract terms come from your signed proposal and are read-only. A contract month's statement compares usage with the commitment and each included allowance; these figures charge nothing.

A commitment is paid by invoice, whole or in installments. Once paid, the amount before tax becomes credits on the invoice's agent, by default the default agent. Usage beyond it is paid by card top-up or an overage invoice, which adds no credits. Balances never go negative.

## Dispute a receipt

![Disputes table with one open dispute and one accepted dispute credited back to the agent](https://mintcdn.com/freebutter/NxHVpA9fr_Nv_dvm/images/console/billing-disputes.webp?fit=max\&auto=format\&n=NxHVpA9fr_Nv_dvm\&q=85\&s=6533fc2a8a97e601ab263d6e0b114158)

Billing → Disputes: each dispute with its receipt and status.

**1. Open the receipt**

Select **Dispute** on the receipt.

**2. Give a reason**

Up to 2000 characters.

**3. Follow it**

Support accepts or rejects it with a note and an optional credit, and emails you.

Signed receipts never change; receipt details add a `disputes` array.

## API

| Route | Returns |
| - | - |
| `GET /v1/org/statements` | Months |
| `GET /v1/org/statements/YYYY-MM?format=json\|csv` | One UTC month; no future months |
| `GET /v1/org/contract` | The active contract, or `null` |
| `POST /v1/org/receipts/{receipt_id}/dispute` `{reason}` | A dispute; `404` for another organization's receipt, `409` if one is open |
| `GET /v1/org/disputes` | Disputes and their status |

`agents` and `totals` hold USD decimal strings:

```jsonc theme={null}
{
  "opening_balance": "10", // Last balance before the month; zero without history.
  "closing_balance": "9", // Last in the month; the opening balance without activity.
  "credits_in": [{ // Funding and refunds by source, with id, date, amount and reason lines.
    "source": "grant", "amount": "1",
    "lines": [{ "id": "<ledger-id>", "date": "2026-06-01T00:00:00Z", "amount": "1", "reason": "Credit grant" }]
  }],
  "credits_in_total": "1",
  "applied": [{ "category": "data", "amount": "2", "count": 1 }], // Spent from credits.
  "applied_total": "2",
  "other_debits": [], // Negative adjustments.
  "other_debits_total": "0",
  "outside_credits": [], // Settled spend paid outside credits.
  "outside_credits_total": "0",
  "reconciliation": {
    "ok": true, // Opening + incoming - applied - other debits equals closing.
    "difference": "0", // Expected minus recorded closing; never rounded.
    "ledger_ids": [] // Opening and period ids when they do not match.
  }
}
```

Statements also list `invoices`; a paid commitment is a credit line with source `invoice_payment`, and dispute refunds a `dispute_refund` line with `dispute_id`. CSV adds `invoices`, `contract` and `overage` rows.

| Contract field | Meaning |
| - | - |
| `public_id` | Contract identifier, beginning `ctr_` |
| `starts_on`, `ends_on` | Inclusive UTC term dates |
| `committed_usd` | Agreed USD commitment, or `null` |
| `included` | USD allowance per receipt category, or `null` |
| `overage_terms` | Agreed terms for excess usage |
| `support_contacts` | Named contacts on each side, in escalation order |
| `service_terms` | Negotiated targets and exclusions |
| `reference` | Proposal or order identifier |

A contract month adds `contract`, from term start to the earlier of month end and term end (`through` is exclusive):

| Statement contract field | Meaning |
| - | - |
| `committed_usd` | Agreed commitment |
| `spend_to_date` | Term usage through that month |
| `remaining_commitment` | Commitment minus usage, floored at zero |
| `included` | Each category's allowance (`amount`), `usage`, `consumed` up to the allowance, and excess `overage` |
| `overage.commitment` | Usage above the commitment |
| `overage.included` | Excess by included category |

The two overages measure the same usage; do not add them. Without a commitment they are `null`. Ended contracts drop out of reads and recalculated statements.


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