> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/api-reference/order-states.md).

# Order States

Interpret sms4sats order lifecycle states and know when to stop polling.

Always use server state as the source of truth. Do not infer order status from elapsed time, payment-wallet UI, or the presence of a phone number alone.

## Bearer-token SMS and rentals

| State                | Meaning                                                      | Client action                                 |
| -------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| `pending_payment`    | Invoice created; payment not accepted                        | Present invoice; allow immediate cancellation |
| `paid`               | Hold accepted                                                | Poll                                          |
| `allocating`         | Provider allocation in progress                              | Poll; do not cancel unless API marks eligible |
| `waiting_for_sms`    | Number assigned, waiting for message                         | Display number; poll                          |
| `code_received`      | Message received; payment confirmation pending               | Preserve message; poll                        |
| `rent_active`        | Rental allocated and active                                  | Display number/messages; poll until end       |
| `settlement_pending` | Fulfillment complete; payment confirmation pending           | Poll; do not create replacement               |
| `release_pending`    | Hold release retrying                                        | Poll; do not create replacement               |
| `expiring`           | Expiry cleanup in progress                                   | Poll                                          |
| `cancelling`         | Cancellation cleanup in progress                             | Poll                                          |
| `completed`          | Fulfilled and finalized                                      | Stop                                          |
| `cancelled`          | User cancellation finalized                                  | Stop                                          |
| `expired`            | Timed out and finalized                                      | Stop                                          |
| `failed`             | Fulfillment failed and payment cleanup completed or recorded | Stop; inspect response/error                  |

## L402 SMS and rentals

The implemented L402 states are `pending_payment`, `paid`, `allocating_number`, `waiting_for_sms`, `rent_active`, `cancel_pending`, `refund_pending`, `refunded`, `refund_failed`, `completed`, and `failed`.

Terminal L402 states are `completed`, `refunded`, `refund_failed`, and `failed`.

## Email

| State               | Meaning                                                |
| ------------------- | ------------------------------------------------------ |
| `pending_payment`   | Hold invoice awaits payment                            |
| `paid`              | Payment accepted; allocation starting                  |
| `waiting_for_email` | Address assigned; waiting for code/message             |
| `code_received`     | Code or message received; payment confirmation pending |
| `completed`         | Delivery and settlement finalized                      |
| `cancelled`         | User cancellation and hold release finalized           |
| `failed`            | Allocation/provider flow failed                        |
| `expired`           | Timed out without delivery                             |

## Robust polling

1. Poll every 5–10 seconds with the same order credential.
2. Use `expiresAt` for display, not as permission to create a duplicate.
3. Continue through transitional payment and cleanup states.
4. Stop only on a documented terminal state.
5. If a request fails transiently, retry polling with exponential backoff and jitter.