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.

CustomerInvoiceListPage.tsx

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.

CustomerInvoiceTablePage.tsx

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:

FilteredInvoiceListPage.tsx

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.

PayableInvoiceListPage.tsx

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>
  );
}