> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoicing Overview

> How Fluxrate generates, finalizes, and delivers invoices to your customers.

Invoicing is the culmination of the billing cycle. Fluxrate automates the entire process — from generating draft invoices to emailing the final document to your customer.

## Invoice Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> DRAFT: Auto-generated at period end
    DRAFT --> OPEN: Finalized (after 1hr grace period)
    DRAFT --> OPEN: Manual finalization
    OPEN --> PAID: Payment received
    OPEN --> VOID: Voided
    OPEN --> UNCOLLECTIBLE: Written off
    UNCOLLECTIBLE --> PAID: Late payment
    UNCOLLECTIBLE --> VOID: Written off permanently
```

## Invoice Statuses

| Status          | Description                                          |
| --------------- | ---------------------------------------------------- |
| `DRAFT`         | Newly created. Editable. Not visible to customer.    |
| `OPEN`          | Finalized and emailed to customer. Awaiting payment. |
| `PAID`          | Payment recorded. Immutable.                         |
| `VOID`          | Cancelled permanently. No payment collected.         |
| `UNCOLLECTIBLE` | Bad debt. Written off.                               |

## How Invoices are Generated

The **invoice generation worker** runs every hour. When a subscription's `current_period_end` has passed:

1. Collects all active charges on the plan
2. For **fixed charges**: Adds the flat amount (prorated if mid-period)
3. For **usage charges**: Queries `UsageEvent` records, applies the meter's aggregation type, multiplies by unit price
4. Calculates tax based on customer and org billing address
5. Creates `Invoice` record with status `DRAFT`
6. Creates `InvoiceLineItem` records for each charge
7. Sets `scheduled_finalize_at = now + 1 hour`

## The 1-Hour Grace Period

After invoice creation, there's a **1-hour review window** before finalization. Use this time to:

* Review the invoice for accuracy
* Adjust line items if needed
* Void the invoice if there was an error

After 1 hour, the **invoice finalizer worker** automatically transitions the invoice from `DRAFT` to `OPEN` and emails the customer.

## Manual Control

You can also manually finalize an invoice:

```bash theme={null}
POST /api/v1/invoices/<invoice_id>/finalize
```

Or send the email manually:

```bash theme={null}
POST /api/v1/invoices/<invoice_id>/send-email
```

## Tax Calculation

Fluxrate calculates tax automatically based on:

* Customer billing address (country, state)
* Organization billing address
* Applicable tax rates

<Note>
  Tax calculation requires the customer to have at minimum a `billing_address_country`. Configure this in the customer's profile.
</Note>

## Invoice Numbering

Invoice numbers follow the format: `INV-{YEAR}-{SEQUENCE}` (e.g., `INV-2025-0042`).