Invoices and usage
What was charged and why, saved cards, the event log and usage charts.
invoices.list and invoices.get
invoices.list takes { "customer_id"?, "status"?, "limit"?, "start_cursor"? }. invoices.get takes { "invoice_id" }.
{
"id": "6707...",
"number": "INV-202610-CSB2NZZ2",
"customer_id": "user_123",
"status": "paid",
"reason": "subscription_cycle",
"currency": "USD",
"subtotal": 2600,
"discount_total": 0,
"credit_applied": 0,
"total": 2600,
"charge_currency": "GHS",
"charge_amount": 40300,
"fx_rate": 15.5,
"lines": [
{ "kind": "base", "description": "Pro", "amount": 2000 },
{ "kind": "usage", "description": "1000 api_calls over the included amount", "quantity": 1000, "amount": 100 },
{ "kind": "usage", "description": "1 seats", "quantity": 1, "amount": 500 }
],
"hosted_invoice_url": "https://revenue.corplandtechnologies.com/invoice/...",
"attempts": 1,
"next_attempt_at": null,
"paid_at": "2026-10-11T14:20:00.000Z"
}| Field | Values |
|---|---|
status | open (waiting for payment), paid, void, uncollectible (retries ran out) |
reason | subscription_create, subscription_update, subscription_cycle, one_off, auto_topup, quantity_change, setup_payment |
line kind | base, proration, credit, usage, quantity, topup, discount, customer_credit, setup |
hosted_invoice_url is a page where the customer can see the lines and pay any open invoice. Plan invoices take a card only (card_only: true) so the card is saved for renewals; credit packs and other one off invoices also take mobile money. Send it in your own emails.
invoices.void and invoices.mark_paid
{ "invoice_id" }. Voiding a renewal ends the plan it was renewing. Marking paid grants whatever the invoice was for, for payments you took another way such as a bank transfer.
payment_methods.list and payment_methods.delete
payment_methods.list takes { "customer_id" } and lists saved cards and wallets with brand, last4, channel, reusable and is_default. Only reusable methods are charged without the customer. payment_methods.delete takes { "customer_id", "payment_method_id" }.
events.list
{ "customer_id"?, "entity_id"?, "feature_id"?, "from"?, "to"?, "limit"?, "start_cursor"? } returns every tracked event, newest first.
events.aggregate
Usage over time for charts.
{ "customer_id": "user_123", "feature_ids": ["messages", "images"], "range": "30d", "bin_size": "day", "group_by": "properties.model" }{
"bin_size": "day",
"list": [{ "period": "2026-10-11T00:00:00.000Z", "values": { "messages": 39, "images": 4 }, "grouped_values": { "messages": { "gpt": 30, "claude": 9 } } }],
"total": { "messages": { "sum": 39, "count": 12 }, "images": { "sum": 4, "count": 4 } }
}range is 24h, 7d, 30d or 90d, or send from and to. bin_size is hour, day or month and is picked for you when left out. Every period in the range is returned, with zeros where nothing happened.