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

# Order lifecycle

> Six states, how to poll them, and what state_reason tells you

An order and each of its items report one of six states. Internal detail is
deliberately not exposed — these six are the contract.

```mermaid theme={null}
flowchart LR
  P[PENDING] --> F[FULFILLED]
  P --> X[FAILED]
  P --> U[UNDER_REVIEW]
  U --> F
  U --> X
  X --> R[REFUND_PENDING]
  U --> R
  R --> D[REFUNDED]
```

<Warning>
  **`UNDER_REVIEW` means the outcome is not yet known with certainty.** It
  resolves to `FULFILLED`, `FAILED` or a refund without you doing anything.
  Re-ordering while an order sits in `UNDER_REVIEW` risks paying for the same card
  twice.
</Warning>

## Polling

| Question            | Answer                                                                 |
| ------------------- | ---------------------------------------------------------------------- |
| How often?          | Every few seconds while `PENDING`. The group limit is 300/min per key. |
| How long?           | Most orders settle in seconds; some take minutes.                      |
| Are there webhooks? | **Not in v1.** Polling is the only mechanism.                          |
| When do I stop?     | At `FULFILLED`, `FAILED` or `REFUNDED`. `REFUND_PENDING` still moves.  |

## `state_reason`

Present on items, `null` unless one of exactly four values applies.

| Value                       | Meaning                                            | Your remedy                                        |
| --------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| `AMOUNT_MISMATCH`           | `amount_minor` did not equal the sum of the items. | Fix your total calculation; re-place the order.    |
| `CURRENCY_COUNTRY_MISMATCH` | The requested currency does not match the product. | Use the product's own currency from the catalogue. |
| `VALIDATION_ERROR`          | Rejected during asynchronous validation.           | Inspect the order; correct and re-place.           |
| `NO_OFFER_AVAILABLE`        | Nothing could serve this item.                     | Retry later, or choose a different denomination.   |

<Note>
  `AMOUNT_MISMATCH` is the cheapest error in the system to avoid and one of the
  more expensive to resolve — the order is accepted, then fails, and raises a
  refund obligation. Compute Σ(`denomination_minor` × `qty`) yourself before
  sending.
</Note>