> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/guides/bill-users-from-usage/.

# Bill your users from usage

Read each customer's Diffio usage for a billing period and turn it into one line on their invoice.

## How it works

1. Your billing job → Diffio API: `GET /usage?start=…&end=…`, Diffio-End-User: customer-42
2. Diffio API → Your billing job: `billable_seconds, list_price_usd`, and by_model
3. Your billing job: `minutes × your price`
4. Your billing job → Your invoices: `one line per customer`

**One request per customer and period; repeat it for each end user you bill.**

## Build it

### 1. Create every project for an end user

Usage is reported per end user only for work created with `Diffio-End-User`. The [SaaS guide](https://diffio.ai/docs/developers/guides/saas-podcast-cleanup/) sends it on every call.

### 2. Read usage for each customer

`GET /usage` with the customer's `Diffio-End-User` and your billing period. `start` and `end` are ISO 8601 dates or times (UTC) and bound when each generation was created; the period can be up to 366 days. Without them, the report is this calendar month so far.

### 3. Price it your way

`billable_seconds` is what the customer used; failed generations count in `generations` and use nothing. `list_price_usd` is that usage at Diffio's list price, for your margin.

### The complete script

Pass the period, then your customers' end user ids (from your own database).

**invoice.py**

```python
"""One invoice line per customer from their Diffio usage in a billing period.

python invoice.py 2026-10-01 2026-11-01 customer-42 customer-7
"""
import math
import sys

from diffio import DiffioClient

start, end, *customers = sys.argv[1:]
PRICE_PER_MINUTE_USD = 0.15  # what you charge your customers
client = DiffioClient()  # reads DIFFIO_API_KEY

for customer in customers:
    # Diffio-End-User narrows the report to this customer's work.
    usage = client.usage.get(start=start, end=end, end_user=customer)
    minutes = math.ceil(usage.billable_seconds / 60)
    print(f"{customer}: {usage.generations} generations, {minutes} min, "
          f"${minutes * PRICE_PER_MINUTE_USD:.2f} (Diffio list price ${usage.list_price_usd:.2f})")
    for row in usage.by_model:
        print(f"    {row.model}: {row.generations} generations, {row.billable_seconds} s")
```

**invoice.mjs**

```javascript
// One invoice line per customer from their Diffio usage in a billing period.
// node invoice.mjs 2026-10-01 2026-11-01 customer-42 customer-7
import { DiffioClient } from "diffio";

const [start, end, ...customers] = process.argv.slice(2);
const PRICE_PER_MINUTE_USD = 0.15; // what you charge your customers
const client = new DiffioClient(); // reads DIFFIO_API_KEY

for (const customer of customers) {
  // Diffio-End-User narrows the report to this customer's work.
  const usage = await client.usage.get({ start, end }, { endUser: customer });
  const minutes = Math.ceil(usage.billable_seconds / 60);
  console.log(
    `${customer}: ${usage.generations} generations, ${minutes} min, ` +
      `$${(minutes * PRICE_PER_MINUTE_USD).toFixed(2)} (Diffio list price $${usage.list_price_usd.toFixed(2)})`
  );
  for (const row of usage.by_model) {
    console.log(`    ${row.model}: ${row.generations} generations, ${row.billable_seconds} s`);
  }
}
```

**cURL**

```bash
curl -sS --connect-timeout 10 --max-time 60 "https://api.diffio.ai/v2/usage?start=2026-10-01&end=2026-11-01" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Diffio-End-User: customer-42"
```

## What you get

| Customer | Usage | Amount |
| --- | --- | --- |
| `customer-42` | 12 generations, 95 min | **$14.25** (list $7.92) |

- One invoice line per customer: generations, minutes and your amount.
- Diffio's list price beside it, and the seconds per model.

**Output of `python invoice.py 2026-10-01 2026-11-01 customer-42`**

**Terminal**

```bash
customer-42: 12 generations, 95 min, $14.25 (Diffio list price $7.92)
    diffio-4.7-flash: 12 generations, 5700 s
```

## API reference

- GET [Get usage](https://diffio.ai/docs/api-reference/usage-summary/) (`/usage`): Fields, period limits and refusals.
- POST [Create a project](https://diffio.ai/docs/api-reference/create-project/) (`/projects`): Diffio-End-User on the work you bill.

## Related pages

- Previous: [Clean up a back catalogue](https://diffio.ai/docs/developers/guides/clean-up-a-back-catalogue/): Folder → restores → usage
- Next: [Podcast cleanup in a SaaS app](https://diffio.ai/docs/developers/guides/saas-podcast-cleanup/): Browser upload → webhook → player
