@blocklet/payment-react/docs/components-history-invoice-list.md

Reusable react components for payment kit v2

# 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.

```tsx CustomerInvoiceListPage.tsx icon=logos:react
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.

```tsx CustomerInvoiceTablePage.tsx icon=logos:react
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:

```tsx FilteredInvoiceListPage.tsx icon=logos:react
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`.

```tsx PayableInvoiceListPage.tsx icon=logos:react
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>
  );
}
```