Components

CustomerInvoiceList

The CustomerInvoiceList component renders a history of invoices for a specific customer or subscription. It supports two display formats: a compact list grouped by date (list) and a detailed, paginated table (table). The component can also display a 'Pay' button for open invoices, initiating the payment flow when clicked.
To function correctly, especially for payment actions and real-time updates, this component must be wrapped within a PaymentProvider.
Props#Prop
Type
Description
Default
customer_id
string
The ID of the customer whose invoices are to be displayed.
''
subscription_id
string
The ID of the subscription for which to display invoices.
''
currency_id
string
Filters invoices by a specific currency ID.
''
include_staking
boolean
If true, includes staking-related invoices in the list.
false
include_return_staking
boolean
If true, includes invoices for returned stakes.
false
include_recovered_from
boolean
If true, includes invoices that were recovered from bad debt.
false
status
string
A comma-separated string of invoice statuses to display (e.g., 'open,paid,uncollectible,void').
'open,paid,uncollectible'
pageSize
number
The number of invoices to display per page.
10
target
string
The target attribute for invoice links (e.g., _self, _blank).
'_self'
action
string
If set (e.g., to 'pay'), a 'Pay' button is rendered for open or uncollectible invoices, triggering the payment flow on click.
''
type
'list' | 'table'
Determines the rendering mode. 'list' groups invoices by date, while 'table' shows a detailed data grid.
'list'
onTableDataChange
(newData, oldData) => void
A callback function that fires when the invoice data is loaded or refreshed.
() => {}
relatedSubscription
boolean
When type is 'table', setting this to true adds a column showing the subscription related to each invoice.
false
Usage Scenarios#Basic Invoice History#To display a simple list of invoices for a particular subscription, set the subscription_id and use the default type='list'.
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryPage({ subscriptionId, session, connectApi }) {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <h2>Invoice History</h2>
      <CustomerInvoiceList
        subscription_id={subscriptionId}
        status="paid,void"
      />
    </PaymentProvider>
  );
}Detailed Invoice Table#For a more detailed view, use type='table'. This mode provides pagination and multiple columns of data. You can also add the relatedSubscription column for invoices linked to multiple subscriptions under one customer.
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function CustomerDashboard({ customerId, session, connectApi }) {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <h3>All Invoices</h3>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        pageSize={20}
        include_staking={true}
        relatedSubscription={true}
        status="open,paid,uncollectible,void"
      />
    </PaymentProvider>
  );
}Invoices with Payment Action#By setting the action prop, you can enable a 'Pay' button for any invoices that are open or uncollectible. Clicking this button will open the payment modal provided by PaymentProvider to complete the transaction.
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function PayInvoices({ customerId, session, connectApi }) {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <h3>Outstanding Invoices</h3>
      <CustomerInvoiceList
        customer_id={customerId}
        status="open,uncollectible"
        action="pay" // This enables the "Pay" button
        type="table"
      />
    </PaymentProvider>
  );
}Real-time Updates#The component automatically subscribes to the invoice.paid WebSocket event. When a customer successfully pays an invoice, the list will refresh in real-time to reflect the new paid status without requiring a page reload.

Prop	Type	Description	Default
`customer_id`	`string`	The ID of the customer whose invoices are to be displayed.	`''`
`subscription_id`	`string`	The ID of the subscription for which to display invoices.	`''`
`currency_id`	`string`	Filters invoices by a specific currency ID.	`''`
`include_staking`	`boolean`	If `true`, includes staking-related invoices in the list.	`false`
`include_return_staking`	`boolean`	If `true`, includes invoices for returned stakes.	`false`
`include_recovered_from`	`boolean`	If `true`, includes invoices that were recovered from bad debt.	`false`
`status`	`string`	A comma-separated string of invoice statuses to display (e.g., 'open,paid,uncollectible,void').	`'open,paid,uncollectible'`
`pageSize`	`number`	The number of invoices to display per page.	`10`
`target`	`string`	The target attribute for invoice links (e.g., `_self`, `_blank`).	`'_self'`
`action`	`string`	If set (e.g., to `'pay'`), a 'Pay' button is rendered for open or uncollectible invoices, triggering the payment flow on click.	`''`
`type`	`'list'` \| `'table'`	Determines the rendering mode. `'list'` groups invoices by date, while `'table'` shows a detailed data grid.	`'list'`
`onTableDataChange`	`(newData, oldData) => void`	A callback function that fires when the invoice data is loaded or refreshed.	`() => {}`
`relatedSubscription`	`boolean`	When `type` is `'table'`, setting this to `true` adds a column showing the subscription related to each invoice.	`false`

Overview

Getting Started

Providers

Components

Guides

Hooks

CustomerInvoiceList

Props#

Usage Scenarios#

Basic Invoice History#

Detailed Invoice Table#

Invoices with Payment Action#

Real-time Updates#

History Components

CustomerPaymentList