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

# Invoice Lifecycle

> Status transitions, finalization rules, and how to manage invoices through their lifecycle.

## Status Transition Rules

Not all status transitions are permitted. Here's what's allowed:

| From            | To              | Allowed?                      |
| --------------- | --------------- | ----------------------------- |
| `DRAFT`         | `OPEN`          | ✅ (finalize)                  |
| `OPEN`          | `PAID`          | ✅                             |
| `OPEN`          | `VOID`          | ✅                             |
| `OPEN`          | `UNCOLLECTIBLE` | ✅                             |
| `UNCOLLECTIBLE` | `PAID`          | ✅ (late payment)              |
| `UNCOLLECTIBLE` | `VOID`          | ✅                             |
| `UNCOLLECTIBLE` | `OPEN`          | ❌ Cannot reopen               |
| `VOID`          | anything        | ❌ Void is permanent           |
| `PAID`          | anything        | ❌ Cannot change paid invoices |

## Managing Invoice Status

### Mark as Paid

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

### Update Status with Note

```bash theme={null}
curl -X PATCH https://api.fluxrate.co/api/v1/invoices/<invoice_id>/status \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "status": "VOID",
    "note": "Duplicate invoice — customer was double-billed"
  }'
```

## Editing Draft Invoices

DRAFT invoices can be edited (line items, due date, customer):

```bash theme={null}
curl -X PUT https://api.fluxrate.co/api/v1/invoices/<invoice_id> \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "due_date": "2025-02-14T00:00:00Z",
    "line_items": [
      {
        "description": "Pro subscription (Feb 2025)",
        "quantity": 1,
        "unit_amount": 49.00
      },
      {
        "description": "API calls overage (12,000 calls)",
        "quantity": 12000,
        "unit_amount": 0.001
      }
    ]
  }'
```

<Warning>
  Only `DRAFT` invoices can be edited. Once finalized to `OPEN`, the invoice is immutable.
</Warning>

## Deleting an Invoice

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

Only `DRAFT` invoices can be deleted. This is permanent.

## Invoice Metadata

Status changes can be annotated with notes and are stored in `meta_data`:

```json theme={null}
{
  "meta_data": {
    "status_change_note": "Customer dispute resolved",
    "status_change_timestamp": "2025-01-15T14:30:00Z",
    "previous_status": "OPEN"
  }
}
```