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

# Invoice lifecycle

> Invoice-specific states, fields, and transitions.

An **invoice** is the primary payment request object in Meum.

## Invoice statuses

| Status             | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `pending`          | Initial or transitional state                                     |
| `awaiting_payment` | Checkout URL active; waiting for customer                         |
| `quoted`           | Checkout quote active with deposit address                        |
| `paid`             | Full payment received and validated                               |
| `underpaid`        | Partial payment received                                          |
| `expired`          | Invoice expired before full payment                               |
| `failed`           | Payment failed                                                    |
| `cancelled`        | Invoice cancelled                                                 |
| `refunded`         | Platform detected refund during status polling (platform-emitted) |

<Note>
  The `refunded` invoice status is set by platform status polling, not by a merchant refund API. Merchant-initiated refunds are **not yet available**.
</Note>

## Key invoice fields

| Field                             | Description                                      |
| --------------------------------- | ------------------------------------------------ |
| `amount`                          | Requested order amount                           |
| `expected_amount`                 | Amount expected after quote (may differ with FX) |
| `received_amount` / `paid_amount` | Actual amount received                           |
| `difference_amount`               | Delta between expected and received              |
| `output_asset`                    | Settlement token identifier                      |
| `checkout_url`                    | Hosted checkout URL                              |
| `expires_at`                      | Expiration timestamp                             |
| `tx_hash`                         | On-chain transaction hash when paid              |

## Idempotent creation

Creating an invoice with the same `store_id` + `external_order_id` returns the existing invoice instead of creating a duplicate.

## Related pages

* [Payment lifecycle](/payments/payment-lifecycle)
* [Payment expiration](/payments/payment-expiration)