# Billing & Account

These hooks provide access to **billing data** — account-level details, invoices, and billing statements from the connected system. They are available when your Limio environment is integrated with a billing provider, such as Zuora.

{% hint style="info" %}
For core user and subscription hooks that work with any billing provider, see the [User & Subscriptions](/developers/limio-sdk/user.md) page.
{% endhint %}

***

## `useUserAccountInformation()`

Returns account-level details from the billing system, including billing configuration and financial metrics.

```typescript
import { useUserAccountInformation } from "@limio/sdk"

const { accountInformation } = useUserAccountInformation()
```

**Returns:**

| Field                | Type             | Description                                   |
| -------------------- | ---------------- | --------------------------------------------- |
| `accountInformation` | `object`         | The Billing account object (see fields below) |
| `revalidate`         | `() => void`     | Refresh the account data                      |
| `mutate`             | `(data) => void` | Optimistically update the local cache         |

The `accountInformation` object contains three sections:

| Section             | Fields                                                                                                            | Description           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `basicInfo`         | `name`                                                                                                            | Account holder name   |
| `billingAndPayment` | `additionalEmailAddresses`, `autoPay`, `billCycleDay`, `paymentTerm`                                              | Billing configuration |
| `metrics`           | `currency`, `totalInvoiceBalance`, `totalDebitMemoBalance`, `unappliedCreditMemoAmount`, `unappliedPaymentAmount` | Financial summary     |

**Example — display account details and balance:**

```tsx
import React from "react"
import { useUserAccountInformation, formatCurrency, getCookie } from "@limio/sdk"

const AccountDetails = () => {
  const { accountInformation } = useUserAccountInformation()
  const locale = getCookie("limio-country")

  const {
    basicInfo: { name },
    billingAndPayment: { autoPay, billCycleDay, paymentTerm },
    metrics: { currency, totalInvoiceBalance, unappliedPaymentAmount }
  } = accountInformation

  return (
    <section>
      <h2>Account Details</h2>
      <table>
        <tbody>
          <tr>
            <td>Account Name</td>
            <td>{name}</td>
          </tr>
          <tr>
            <td>Bill Cycle Day</td>
            <td>{billCycleDay}</td>
          </tr>
          <tr>
            <td>Payment Term</td>
            <td>{paymentTerm}</td>
          </tr>
          <tr>
            <td>Auto Pay</td>
            <td>{autoPay ? "Enabled" : "Disabled"}</td>
          </tr>
          <tr>
            <td>Invoice Balance</td>
            <td>{formatCurrency(totalInvoiceBalance, currency, locale)}</td>
          </tr>
          <tr>
            <td>Unapplied Payments</td>
            <td>{formatCurrency(unappliedPaymentAmount, currency, locale)}</td>
          </tr>
        </tbody>
      </table>
    </section>
  )
}
```

<details>

<summary>Example <code>accountInformation</code> object</summary>

```javascript
{
  basicInfo: {
    name: "Jane Smith"
  },
  billingAndPayment: {
    additionalEmailAddresses: ["billing@leemeeo.com"],
    autoPay: true,
    billCycleDay: 9,
    paymentTerm: "Net 30"
  },
  metrics: {
    currency: "USD",
    totalInvoiceBalance: 29.00,
    totalDebitMemoBalance: 0,
    unappliedCreditMemoAmount: 0,
    unappliedPaymentAmount: 0
  }
}
```

</details>

***

## `useUserInvoices()`

Returns a paginated list of the Billing system invoices for the authenticated user.

```typescript
import { useUserInvoices } from "@limio/sdk"

const { invoices, revalidate, nextPage } = useUserInvoices(pageSize, page)
```

**Parameters:**

| Param      | Type     | Default | Description                 |
| ---------- | -------- | ------- | --------------------------- |
| `pageSize` | `number` | `40`    | Number of invoices per page |
| `page`     | `number` | `1`     | Page number to retrieve     |

**Returns:**

| Field        | Type                | Description                              |
| ------------ | ------------------- | ---------------------------------------- |
| `invoices`   | `ZuoraInvoice[]`    | Array of invoice objects                 |
| `revalidate` | `() => void`        | Refresh the invoices data                |
| `mutate`     | `(invoice) => void` | Optimistically update a specific invoice |
| `nextPage`   | `string`            | Pagination token for the next page       |

Each invoice object includes fields such as `invoiceNumber`, `amount`, `status`, `invoiceDate`, and `dueDate`.

**Example — display invoices with status:**

```tsx
import React from "react"
import { useSubscriptions, useUserInvoices } from "@limio/sdk"

const InvoiceList = () => {
  const { invoices } = useUserInvoices()

  if (!invoices?.length) {
    return <p>No invoices found.</p>
  }

  return (
    <section>
      <h2>Invoices</h2>
      {invoices.map((invoice) => (
        <div key={invoice.invoiceNumber}>
          <div>
            <span>Invoice: {invoice.invoiceNumber}</span>
            <span>Status: {invoice.status}</span>
          </div>
          <div>
            <span>Date: {invoice.invoiceDate}</span>
            <span>Due: {invoice.dueDate}</span>
          </div>
          <div>
            <span>Amount: ${invoice.amount.toFixed(2)}</span>
          </div>
        </div>
      ))}
    </section>
  )
}
```

<details>

<summary>Example invoice object</summary>

```javascript
{
  invoiceNumber: "INV-00042391",
  amount: 29.00,
  status: "Posted",
  invoiceDate: "2025-06-09",
  dueDate: "2025-07-09"
}
```

</details>

***

## `sendSummaryStatementEmail()`

Triggers a summary statement from the Billing system email for the authenticated user's account. The statement covers all billing activity from the given start date to the current date.

```typescript
import { sendSummaryStatementEmail } from "@limio/sdk/zuora"

const result = await sendSummaryStatementEmail("2025-01-01")
```

**Parameters:**

| Param       | Type     | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| `startDate` | `string` | Start date for the statement period (`YYYY-MM-DD` format) |

**Returns:** `{ success: boolean }` — indicates whether the email was successfully queued.

**Example — send billing statement button:**

```tsx
import React, { useState } from "react"
import { sendSummaryStatementEmail } from "@limio/sdk/zuora"

const SendStatementButton = () => {
  const [sent, setSent] = useState(false)

  const handleClick = async () => {
    const result = await sendSummaryStatementEmail("2025-01-01")
    setSent(result.success)
  }

  return (
    <div>
      <button onClick={handleClick} disabled={sent}>
        {sent ? "Statement sent" : "Email billing statement"}
      </button>
      {sent && <p>A summary statement has been sent to your email.</p>}
    </div>
  )
}
```

***

## `LimioFetchers.invoiceFetch()` — Downloading invoice PDFs

Fetches an invoice file (PDF) from Zuora as a blob. Use this to build "Download invoice" buttons in your invoice list or subscription overview components.

```typescript
import { LimioFetchers } from "@limio/sdk"
import { useUser } from "@limio/sdk"
```

**Example — download button for an invoice row:**

```tsx
import React from "react"
import { LimioFetchers } from "@limio/sdk"
import { useUser } from "@limio/sdk"

const DownloadInvoiceButton = ({ invoiceId }) => {
  const { token } = useUser()

  const handleDownload = async () => {
    const blob = await LimioFetchers.invoiceFetch(
      `api/plugins/zuora/invoices/file/${invoiceId}`,
      token
    )

    const url = URL.createObjectURL(blob)
    const link = document.createElement("a")
    link.href = url
    link.download = `invoice-${invoiceId}.pdf`
    link.click()
    URL.revokeObjectURL(url)
  }

  return <button onClick={handleDownload}>Download PDF</button>
}
```

**Parameters:**

| Param   | Type     | Description                            |
| ------- | -------- | -------------------------------------- |
| `path`  | `string` | API path for the invoice file endpoint |
| `token` | `string` | Authentication token from `useUser()`  |

**Returns:** `Blob` — the invoice file data.

***

## See also

* [User & Subscriptions](/developers/limio-sdk/user.md) — Core hooks for user identity, subscriptions, addresses, and payment methods
* [Subscription Update Checkout](/developers/limio-sdk/subscription-update-checkout.md) — How to build plan change flows


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.limio.com/developers/limio-sdk/billing-account.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.