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

# Invoicing

> Create, approve, share, and reconcile invoices from the dashboard.

An invoice in Caratuva is a request to collect a specific amount from a specific buyer. Each invoice has its own lifecycle, its own audit trail, and its own hosted payment link.

You can manage invoices two ways:

* **From the dashboard** — covered in this guide. Caratuva is your invoice system of record.
* **From your ERP via API** — see [Payment intents](/api-reference/payment-intents). Your ERP keeps the invoice; Caratuva handles collection.

Both paths produce identical buyer experiences and identical webhook events. Pick whichever matches your operating model.

## Lifecycle

```
draft → awaiting_approval → approved → awaiting_buyer
                                     → buyer_kyc_pending
                                     → buyer_kyc_approved
                                     → fx_quoted
                                     → on_ramp_pending
                                     → fiat_received
                                     → offramp_pending
                                     → settled
```

`settled` is the terminal success state. The terminal non-success states are `expired`, `cancelled`, and `buyer_kyc_rejected`. `on_ramp_failed` and `offramp_failed` are in-flight failures that can be retried rather than terminal. (This is a simplified view; a few intermediate/retry statuses are omitted.)

## Creating an invoice

From the dashboard, go to **Invoices** and click **New** to open the create form.

### Header

* **Buyer** — name, email, country. The email is where the payment-link invitation lands. Pick carefully; sending to the wrong address means restarting from a fresh invoice.
* **Currency** — the buyer's currency (USD, EUR, or BRL). Caratuva quotes the FX into BRL automatically when the buyer confirms.
* **Amount** — what the buyer pays you. Two-decimal precision. \*\*USD invoices must be at least US$10.00** — buyers fund by bank transfer, which has a US$10 minimum, so a smaller USD invoice can't be paid online.
* **Due date** *(optional)* — the invoice expires automatically if not paid by then.
* **Reference / external ID** *(optional)* — your internal order number. Round-trips onto every webhook so your ERP can match.

### Line items

Add as many line items as you like. Each carries a description, quantity, unit price, and subtotal. Line items render verbatim on the buyer's payment page — they're for the buyer's clarity, not for tax classification (Caratuva doesn't validate NCM, HS, or origin codes here).

### Export details *(optional)*

The form also collects export-specific fields when relevant: DU-E number, export contract reference, incoterm, and port of loading. These help your own records and reconciliation. (A free-text buyer-facing "notes" block exists only on the API payment-intents surface, not on this dashboard form.)

### Save

Saving puts the invoice into `draft`. From here you can edit freely. Once you're happy, click **Submit for approval**.

## Approval (four-eyes)

Caratuva supports a four-eyes rule for larger disbursements. Your organization can set an **approval threshold**: any invoice whose amount meets or exceeds it is created in `awaiting_approval`, and **the teammate who created it cannot approve it** — a different teammate must. Invoices below the threshold (or any invoice if no threshold is set) go straight to `draft` and can be approved by the same person who created them. It's a deliberate compliance control, focused where the amounts are large enough to matter.

When an invoice needs approval:

1. The invoice is created in `awaiting_approval` instead of `draft`.
2. Your other teammates are notified that an invoice is waiting.
3. A teammate other than the creator opens the invoice, reviews, and either **approves** or **rejects**.
4. Approval transitions the invoice to `approved`. Rejection transitions it to `cancelled` and records the reason.

If your team is small, add a second teammate so above-threshold invoices have a separate approver — the creator can't approve their own. Above-threshold invoices must be created from the dashboard by a person, not via an API key.

## Inviting the buyer

Once approved, click **Invite buyer**. Caratuva emails the buyer a magic-link to the hosted payment page on `pay.caratuva.com`. The invoice transitions to `awaiting_buyer`.

You can also:

* **Copy the link** — share it through your own channel (CRM, ERP, WhatsApp, etc.). The link is unguessable but not secret-bearing on its own — sign-in still requires the buyer's email.
* **Re-send the invitation** — for buyers who lost the original email. There is a per-buyer-email rate limit to prevent inbox flooding.

See [Payment links](/payment-links) for what the buyer sees from here.

## Watching settlement

The invoice detail page shows a live timeline of every state transition with a timestamp. The same events are also delivered as outbound webhooks; see [Webhooks](/api-reference/webhooks).

Two states matter most for ops:

* **`settled`** — funds have landed in your registered Brazilian bank account via PIX. Mark the order paid in your downstream systems.
* **`buyer_kyc_rejected`** — terminal: the buyer failed identity verification. In-flight failures `on_ramp_failed` and `offramp_failed` are retryable rather than terminal; the detail page shows the exact reason in each case.

## Cancelling an invoice

You can cancel an invoice up to and including `fx_quoted` — that is, any time before the buyer funds the on-ramp. From `on_ramp_pending` onward the buyer's payment is already in flight and the invoice can no longer be cancelled; any reversal then happens through your downstream systems.

Cancellation requires a reason (free-text). The buyer is automatically notified that the invoice is no longer payable.

## Editing after creation

An invoice stays editable while it's in `draft` or `awaiting_approval`. It becomes immutable once **approved** — the invoice you approve is the invoice the buyer pays. If the buyer or amount is wrong after approval, cancel and create a new one. (You can also use **Reassign buyer** from the detail page to move an invoice to a different buyer when a KYC flow is stuck.)

## Bulk operations

Bulk creation is API-only — see [Payment intents](/api-reference/payment-intents). The dashboard list view does not currently offer bulk export.

## Tips

* **Use the reference / external ID field.** Even if you operate primarily from the dashboard, a stable external ID makes it trivial to reconcile against your accounting system later.
* **Set due dates aggressively.** A 7-day due date keeps your AR clean and makes follow-up automatic.
* **Test in test mode first.** A new buyer in test mode lets you walk the entire flow yourself and learn what your buyers will see.