CustomerInvoiceList

The CustomerInvoiceList component is designed to render a customer's invoice history. It fetches and displays invoice data from the payment service, offering two distinct layouts: a simple, date-grouped list with infinite scroll, and a detailed, paginated table. This component must be used within a PaymentProvider to function correctly.

Props#

Prop	Type	Description	Default
customer_id	string	The ID of the customer whose invoices are to be displayed.	''
subscription_id	string	Filter invoices by a specific subscription ID.	''
currency_id	string	Filter 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 return staking invoices.	false
include_recovered_from	boolean	If true, includes invoices that were recovered from a previous balance.	false
status	string	A comma-separated string of invoice statuses to display (e.g., 'open,paid,uncollectible').	'open,paid,uncollectible'
pageSize	number	The number of invoices to fetch per page.	10
target	string	The target attribute for invoice links (e.g., '_self', '_blank').	'_self'
action	string	Defines a call-to-action for certain invoices. Set to 'pay' to show a pay button for open invoices.	''
type	'list' | 'table'	The display mode for the invoice list.	'list'
onTableDataChange	Function	A callback function that is triggered when the invoice data changes.	() => {}
relatedSubscription	boolean	In table mode, if true, shows a column with a link to the related subscription.	false

Basic Usage (List View)#

The default view (type="list") renders a simple list of invoices, grouped by date, with an infinite scroll mechanism to load more items.

import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryPage() {
  // Assuming customerId is available, e.g., from session or props
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList customer_id={customerId} />
    </PaymentProvider>
  );
}

Table View#

For a more detailed and structured presentation, you can set type="table". This mode displays invoices in a paginated table with sortable columns.

import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryTable() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        relatedSubscription={true} // Show a column for the related subscription
        pageSize={5}
      />
    </PaymentProvider>
  );
}

In this example, the relatedSubscription prop is enabled to add a column that links directly to the subscription associated with each invoice, which is useful for subscription-based services.

Filtering Invoices#

You can use various props to filter the invoices displayed. For example, to show only paid invoices related to staking:

import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function FilteredInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        status="paid" // Only show paid invoices
        include_staking={true} // Also include staking transactions
      />
    </PaymentProvider>
  );
}

Enabling Payments for Open Invoices#

By setting the action prop to 'pay', you can add a "Pay" button to any invoices with open or uncollectible status. Clicking this button will initiate the payment flow using the connect instance from PaymentProvider.

import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function PayableInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        status="open,uncollectible" // Show only invoices that need payment
        action="pay" // Add a "Pay" button
      />
    </PaymentProvider>
  );
}