Preview a billing run
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.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
application/json- body
asOf?stringThe cut-off: only sales made at or before this count. Unset, now
date-timeCreated
application/json- response
Created
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 POST "https://example.com/v1/billing-runs" \ -H "Content-Type: application/json" \ -d '{}'{ "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"}