Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/developers/guides/bill-users-from-usage.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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. 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 sends it on every call.

  2. 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. 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
"""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")

What you get

October 2026 invoice line, from the example run below
CustomerUsageAmount
customer-4212 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
customer-42: 12 generations, 95 min, $14.25 (Diffio list price $7.92)
    diffio-4.7-flash: 12 generations, 5700 s

API reference

  • GETGet usage (/usage): Fields, period limits and refusals.
  • POSTCreate a project (/projects): Diffio-End-User on the work you bill.

Report an issue with this page