Let customers download the usage behind each invoice

How to do it

Finance teams split a usage bill across projects and clients. They need the detail, and an export saves a support ticket for every invoice. Build the export from the same raw events as the invoice, as Keep raw events and derive every total from them says. Leave out personal data the billing contact may not see, such as prompts or end-user names. Stream large exports as a file, as in Run long jobs asynchronously.

Examples

Python example

import csv

def write_usage_export(rows, out) -> None:
    writer = csv.writer(out)
    writer.writerow(["occurred_at", "meter", "quantity", "reference"])
    for row in rows:
        writer.writerow([row.occurred_at.isoformat(), row.meter, row.quantity, row.reference or ""])

JavaScript example

import { stringify } from 'csv-stringify'

export function usageExportStream(rows) {
  const csv = stringify({ header: true, columns: ['occurred_at', 'meter', 'quantity', 'reference'] })
  for (const row of rows) csv.write([row.occurredAt.toISOString(), row.meter, row.quantity, row.reference ?? ''])
  csv.end()
  return csv
}

How to check

A test downloads the export for an invoice and sums the quantity per meter. Each sum equals the quantity on that meter's invoice line. The export contains no prompt text.

Related rules

• USG-3 Keep raw events and derive every total from them in Usage-based billing
• API-37 Run long jobs asynchronously in API design