Overview The InvoicesClient provides read-only access to billing invoices. It’s used to display billing history to end users. Invoice creation is handled automatically by the payment pipeline and is not accessible from the SDK.
Methods list() List invoices with optional filters.
const response = await revstack . invoices . list ( params );
Filter and pagination parameters. Filter by customer ID. Example: "usr_abc123"
Filter by subscription ID. Example: "sub_abc123"
Filter by invoice status. Example: "paid", "open", "void"
Maximum number of records to return.
Number of records to skip.
response
PaginatedResponse<Invoice>
A paginated list of invoices. Array of invoice records.
Total number of records matching the query.
Whether more records exist beyond this page.
Example: // List invoices for a customer's billing history page const { data : invoices } = await revstack . invoices . list ({ customerId: "usr_abc123" , status: "paid" , }); for ( const invoice of invoices ) { console . log ( `Invoice ${ invoice . id } : ${ invoice . amount } ` ); }
get() Retrieve a single invoice by ID.
const invoice = await revstack . invoices . get ( invoiceId );
The invoice’s unique identifier. Example: "inv_abc123"
The invoice record. Unique identifier with inv_ prefix.
The subscription this invoice belongs to.
Invoice amount in the smallest currency unit (e.g. cents).
ISO 4217 currency code (max 3 characters). Example: "USD", "EUR"
Invoice status: draft, open, paid, void, uncollectible.
Reason the invoice was created. Example: "subscription_create", "subscription_cycle", "manual"
ISO 8601 timestamp of when the invoice was paid.
ISO 8601 timestamp of creation.
Example: const invoice = await revstack . invoices . get ( "inv_abc123" ); console . log ( `Amount: $ ${ invoice . amount / 100 } ` ); console . log ( `Status: ${ invoice . status } ` ); console . log ( `Paid: ${ invoice . paidAt } ` );
Common Use Cases Billing History Page // Display customer's invoice history async function getBillingHistory ( customerId : string ) { const { data : invoices } = await revstack . invoices . list ({ customerId , limit: 50 , }); return invoices . map ( inv => ({ id: inv . id , date: new Date ( inv . createdAt ! ). toLocaleDateString (), amount: `$ ${ ( inv . amount / 100 ). toFixed ( 2 ) } ` , status: inv . status , reason: inv . billingReason , })); }
Invoice Details View // Show detailed invoice information async function getInvoiceDetails ( invoiceId : string ) { const invoice = await revstack . invoices . get ( invoiceId ); return { invoiceNumber: invoice . id , amount: invoice . amount / 100 , currency: invoice . currency , status: invoice . status , billingReason: invoice . billingReason , createdDate: invoice . createdAt , paidDate: invoice . paidAt , }; }
Payment Status Check // Check if a specific invoice has been paid async function isInvoicePaid ( invoiceId : string ) : Promise < boolean > { const invoice = await revstack . invoices . get ( invoiceId ); return invoice . status === "paid" ; }
Subscription Invoices // Get all invoices for a subscription async function getSubscriptionInvoices ( subscriptionId : string ) { const { data : invoices } = await revstack . invoices . list ({ subscriptionId , }); return invoices . sort (( a , b ) => new Date ( b . createdAt ! ). getTime () - new Date ( a . createdAt ! ). getTime () ); }
Total Revenue Calculation // Calculate total revenue from paid invoices async function calculateRevenue ( customerId : string ) { const { data : invoices } = await revstack . invoices . list ({ customerId , status: "paid" , }); const total = invoices . reduce (( sum , inv ) => sum + inv . amount , 0 ); return { total: total / 100 , // Convert cents to dollars count: invoices . length , currency: invoices [ 0 ]?. currency ?? "USD" , }; }
Outstanding Invoices // Get unpaid invoices for a customer async function getOutstandingInvoices ( customerId : string ) { const { data : invoices } = await revstack . invoices . list ({ customerId , status: "open" , }); const totalDue = invoices . reduce (( sum , inv ) => sum + inv . amount , 0 ); return { invoices , count: invoices . length , totalDue: totalDue / 100 , }; }
Invoice Export // Export invoices to CSV format async function exportInvoices ( customerId : string ) { const { data : invoices } = await revstack . invoices . list ({ customerId , }); const csv = [ "Invoice ID,Date,Amount,Currency,Status,Reason" , ... invoices . map ( inv => ` ${ inv . id } , ${ inv . createdAt } , ${ inv . amount / 100 } , ${ inv . currency } , ${ inv . status } , ${ inv . billingReason } ` ), ]. join ( " \n " ); return csv ; }
