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

# Invoices Lifecycle

> Understand invoice states and how to manage them from creation to payment.

## Invoice states

### DRAFT

Invoice is being prepared. Can be modified or deleted.

* No invoice number or date
* Does not affect AP/AR balances
* Can update amounts, line items, tax
* Can be deleted

### FINALIZED

Invoice is issued and official. Cannot be modified.

* Has sequential invoice number
* Has official invoice date
* Due date calculated (if payment\_terms provided)
* Affects AP/AR balances
* Immutable - corrections require credit notes

### CANCELLED

Invoice is voided (not yet implemented).

## State transitions

```
DRAFT → finalize() → FINALIZED
```

### Creating an invoice

All invoices start as DRAFT:

```bash theme={null}
curl https://api.nocotax.app/invoices \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "items": [
      {
        "description": "Monthly Subscription",
        "quantity": 1,
        "unit_extratax_amount": 9900
      }
    ]
  }'
```

### Finalizing an invoice

```bash cURL theme={null}
curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}
```

What happens on finalization:

1. Invoice number assigned
2. Invoice date set to today
3. Due date calculated (from payment\_terms)
4. AP/AR balances updated
5. Invoice locked from changes

> [!WARNING]
>
> Finalization is irreversible. Review carefully before finalizing.

## Payment status

Finalized invoices track payment status:

| Status | Description |
| - | - |
| **OPEN** | Due date not yet passed, unpaid |
| **DUE** | Past due date, unpaid, or partially paid |
| **PAID** | Fully paid |

The `amount_remaining` field shows what's still owed.

## Working with finalized invoices

### Attaching payments

> [card] [Invoice Payments](https://nocotax.mintlify.site/billing-invoicing/invoices/payments.md)

### Correcting errors

Issue a credit note for finalized invoices:

```bash theme={null}
curl https://api.nocotax.app/credit_notes \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "invoice_id": 'inv_123',
    "items": [
      {
        "description": "Monthly Subscription",
        "quantity": 1,
        "unit_extratax_amount": 9900
      }
    ]
  }'
```

## Best practices

* Review drafts carefully before finalizing
* Finalize invoices promptly - don't leave in DRAFT
* Use payment\_terms for automatic due date calculation
* Issue credit notes for corrections, never modify finalized invoices
* Track payment status for automated reminders


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.