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

# Monthly Statement

> What to invoice your clients this month — setup fees and prorated line charges, per client, per line. For agencies Tuco invoices offline.

<Note>
  For agencies **Tuco invoices offline**. Tuco bills you for the whole group, so
  your client workspaces have no card and no Stripe subscription — which leaves
  you working out what to charge each client by hand. This does the arithmetic.

  It **charges nothing**. You still send your own invoice.
</Note>

## Endpoint

* **Method**: `GET`
* **Path**: `/api/agency/statement`
* **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys))

## Query parameters

| Name | Required | Notes |
| - | - | - |
| `month` | no | `YYYY-MM`. Defaults to the current UTC month. Anything else is a `400` |
| `format` | no | `csv` for a spreadsheet download. Omit for JSON |

## How a line is priced

| | |
| - | - |
| **Setup** | Charged **once, in full**, in the month the line was ordered. Never prorated — it paid for provisioning work, not for time |
| **Monthly** | Prorated: `rate × billable days ÷ days in month` |
| **Billing starts** | The day the line is **ordered**, not the day it goes live. The provisioning wait is billable |
| **Cancelling** | Billed through the **end of the month** it takes effect, so the final month is always a full month |

Rates come from your agency's pricing, the same one the rest of Tuco uses. Each
workspace reports the `setupRateCents` and `monthlyRateCents` it was priced at,
so a number is always traceable to a rate.

## Example request

```bash theme={null}
curl "https://app.tuco.ai/api/agency/statement?month=2026-10" \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx"
```

## Success response (200)

```json theme={null}
{
  "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx",
  "month": "2026-10",
  "periodStart": "2026-10-01T00:00:00.000Z",
  "periodEnd": "2026-10-31T23:59:59.999Z",
  "currency": "usd",
  "workspaces": [
    {
      "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
      "name": "Acme Roofing",
      "plan": "growth",
      "setupRateCents": 16800,
      "monthlyRateCents": 14500,
      "lines": [
        {
          "lineId": "68c1f0a7d2b4e91f3c7a55e2",
          "identifier": "+14155550134",
          "channelType": "phone",
          "orderedAt": "2026-09-10T11:02:00.000Z",
          "endsAt": null,
          "status": "active",
          "billableDays": 31,
          "daysInMonth": 31,
          "setupCents": 0,
          "monthlyCents": 14500,
          "totalCents": 14500,
          "fullMonth": true
        },
        {
          "lineId": "68c1f0a7d2b4e91f3c7a55e9",
          "identifier": "+14155550198",
          "channelType": "phone",
          "orderedAt": "2026-10-20T09:14:00.000Z",
          "endsAt": null,
          "status": "provisioning",
          "billableDays": 12,
          "daysInMonth": 31,
          "setupCents": 16800,
          "monthlyCents": 5613,
          "totalCents": 22413,
          "fullMonth": false
        }
      ],
      "setupCents": 16800,
      "monthlyCents": 20113,
      "totalCents": 36913
    }
  ],
  "newLines": 1,
  "activeLines": 2,
  "setupCents": 16800,
  "monthlyCents": 20113,
  "totalCents": 36913
}
```

Every amount is in **cents**. Each line item is rounded to the nearest cent and
the totals are sums of the rounded items, so the rows always add up to the
total you print.

Reading the second line above: ordered on 20 October, so setup is charged in
full and the month is prorated at 12 of 31 days — `14500 × 12 ÷ 31 = 5613`.

## Fields

| Field | |
| - | - |
| `billableDays` / `daysInMonth` | The proration, shown so a client can check it |
| `fullMonth` | `true` when the line ran the whole month and `monthlyCents` is the undivided rate |
| `orderedAt` | When billing started for this line |
| `endsAt` | When it stops, or `null` while it is running |
| `newLines` | Lines ordered this month — the ones carrying a setup fee |
| `activeLines` | Lines still running at period end |

## CSV

```bash theme={null}
curl "https://app.tuco.ai/api/agency/statement?month=2026-10&format=csv" \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" -o statement.csv
```

One row per line, plus a `TOTAL` row, with dollar amounts rather than cents —
ready to paste into whatever you invoice from.

## Error responses

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_MONTH` | `month` is not `YYYY-MM` |
| `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key |
| `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used |
| `409` | `NOT_INVOICED` | Your clients are billed through Stripe — their real invoices and your MRR are on the Billing tab |

<Note>
  A Stripe-billed agency gets a `409` on purpose. It already has real Stripe
  invoices; a second set of numbers computed a different way would be two
  sources of truth that can disagree.
</Note>

## In the dashboard

The same statement is the **Billing** tab in your agency view — month picker,
totals, a per-client breakdown you can expand to individual lines, and the same
CSV. No API key needed.


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