Get a billing run
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
id*stringSuccess
application/json- response
Success
id*stringasOf*stringThe cut-off this run fixed: only sales made at or before it count
date-timestatus*stringpreviewed is waiting to be committed. committing is being billed by the worker. completed billed every row. completed_with_failures billed what it could; commit it again to retry the rows that failed
"previewed""committing""completed""completed_with_failures"rows*array<>One row per (customerId, currency) pair with eligible, uninvoiced sales
truncated*booleanTrue when you had more customers waiting than the 1000 rows one run holds: this run covers the lowest customer ids, and the rest come up in your next run once these are invoiced
createdAt*stringdate-timeupdatedAt*stringdate-timecurl -X GET "https://example.com/v1/billing-runs/brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"{ "id": "brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "asOf": "2026-10-07T11:04:31.000Z", "status": "previewed", "rows": [ { "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "currency": "USD", "saleIds": [ "sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA" ], "subtotal": 2878, "tax": 2878, "taxLines": [ { "name": "string", "rateBps": 2000, "amount": 2878 } ], "total": 2878, "status": "pending", "reason": "string", "invoiceId": "inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA" } ], "truncated": true, "createdAt": "2026-10-07T11:04:31.000Z", "updatedAt": "2026-10-07T11:04:31.000Z"}Preview a billing run POST
Computes, but does not create, one invoice per `(customerId, currency)` pair that has eligible, uninvoiced sales made at or before `asOf`: the same rules `POST /invoices` already enforces, applied to every customer at once, at most 500 sales per row, oldest first. Nothing is written to your sales or invoices; nothing bills a customer until a run is committed. One run holds at most 1000 rows: with more customers waiting than that, `truncated` is true and the rest come up in your next run.
Commit a billing run POST
Starts billing every `pending` row of a `previewed` run: raises the invoices, one per row, with the exact sales the preview fixed. Returns as soon as the run moves to `committing`; a background worker finishes it, so poll `GET /billing-runs/{id}` for progress. Calling this again on a `completed_with_failures` run retries only the rows still `failed`, leaving every `done`, `skipped` and `excluded` row untouched, so it is always safe to repeat.