Reseller Usage Metering API
For platforms reselling Orbit to their own customers — agencies, MSPs, vertical SaaS. Send a batch of your end customers’ usage events with a custom meter definition, and get back a rated, per-subaccount rollup plus the wallet-ledger and invoice draft you would bill each subaccount with. This is a programmatic partner endpoint: you already hold your end customers’ usage events in your own system, so you POST them here and get the rated result back. It is stateless — nothing is persisted and no wallet or invoice is charged. Use it to rate a billing period, preview the numbers, and (optionally) render the branded invoice you hand your customer. Resolving a tax-exemption certificate is a control your organization’s billing team owns: you pass the resolved certificate into the request, and the invoice draft foots accordingly. Base path:/api/v1/usage/meters
Authentication: Organization session JWT or an owner/admin API key. You only ever rate your own payload.
Rate a batch
Rollup usage events
POST /api/v1/usage/meters/rollup
Rate a batch of metered events against a custom meter and return the rollup. Each event names the subaccount that incurred it and a quantity; the meter defines the included quantity and the graduated overage tiers used to price the overflow.
Meter definition
Request body
Invoice metadata
Supply the optionalinvoice block to also receive a branded, standalone HTML invoice (billing.invoice.rendered_html) for the marked-up draft — the document you hand your end customer.
All amounts are in minor currency units (cents). The
billing block is a preview of the write descriptors — the wallet-ledger debits and the invoice draft you would charge each subaccount with. This endpoint does not commit them; persisting the ledger and invoice writes is a separate step in your own billing flow.Tax exemption — the approved vs. reverted branch
The invoice branch is deterministic: anapproved exemption certificate whose jurisdiction matches tax.jurisdiction (or is a blanket certificate with no jurisdiction) and whose validity window covers the rating period suppresses the tax line entirely. Any other status — pending, rejected, or expired — taxes the invoice as normal, so an approved certificate whose validity window has lapsed reverts to a taxed invoice even though the status itself still reads approved. The invoice echoes the outcome so you can audit it: tax_exemption_status mirrors the status you passed, and tax_exemption_applied is true only when tax was actually suppressed.
status: "rejected", an expired status, or an approved status whose valid_to has already lapsed) — the tax line comes back:
billing.invoice block for readability — the rest of the envelope is unchanged. When the exemption matches, the rendered document (if you asked for one) omits the tax row; when it reverts, the tax row comes back.
A blanket exemption (no
jurisdiction on the certificate) matches any tax.jurisdiction. A certificate that names a jurisdiction matches case-insensitively, but never against an absent or mismatched tax.jurisdiction.Call it from the SDKs
The typed SDK has no usage-metering helper yet, so both endpoints go through the genericrequest() escape hatch (or raw fetch) — the same pattern the event-sinks page uses:
client.request() escape hatch above. See the Python SDK.
Swap the path to /api/v1/usage/meters/credit-note to issue a credit note the same way. request() attaches your API key, retries 429/5xx with backoff, and returns the same { data, meta } envelope a raw call returns — fetch() with an X-API-Key header works identically.
Issue a credit note
Credit a prior charge
POST /api/v1/usage/meters/credit-note
Issue a credit note (credit memo) or a manual invoice adjustment against a charge you already billed a downstream customer. A credit note reduces what the customer owes on their invoice — use it for an overbilled line, a goodwill credit, a negotiated discount, or a billing-error correction. Unlike a Stripe refund it moves no money on a card; it produces the finance document you hand your customer.
Like the rollup endpoint it is stateless — nothing is persisted. It returns the credited totals and, when you supply a credit_note block, a branded, standalone HTML credit note (credit_note.rendered_html).
Request body
Credit-note metadata
Amounts are in minor currency units (cents), and the totals are the credited (owed-back) figures. This endpoint does not persist the credit note or apply it to a wallet — record it and apply it against the invoice in your own billing flow.
Totals-only responses
Thecredit_note block is optional on this endpoint (just as invoice is optional on rollup). Omit it and the rated/credited totals come back without any rendered HTML — the shape you’d poll programmatically or preview before printing a document. Conversely, pair a tax/exemption combination like the rollup samples above and supply or suppress the document block the same way — for example, omit invoice from an exemption-suppressed rollup call and billing.invoice still carries tax_exemption_status: "approved" and tax_exemption_applied: true, just without rendered_html:
original_total_minor guard works the same either way: a credit whose total exceeds the original invoice’s tax-inclusive total is rejected with a 422, whether or not you asked for the document.