> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Order lifecycle overview

> Every letter moves through the same four phases — compose, proof, dispatch, track. What happens in each, and where to go deeper.

Whatever surface you send from — API, MCP, the web composer, an embed widget, a CSV bulk import, or a forwarded email — every letter moves through the same four phases. This page is the map. Each phase links to the guide that covers it in depth; nothing below duplicates that detail.

| Phase                 | Question it answers                                        | Owns which states                                                 |
| --------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| [Compose](#compose)   | What is this letter, and who's it going to?                | *(pre-order)*                                                     |
| [Proof](#proof)       | Is this exactly what should print, for exactly this price? | *(pre-order)*                                                     |
| [Dispatch](#dispatch) | Is it paid for, verified, and handed to a printer?         | `pending_payment` → `screening` → `held_for_review` → `submitted` |
| [Track](#track)       | Where is it now, and can I still stop it?                  | `mailed` → `delivered` (or `canceled` / `refused` / `failed`)     |

See the [error contract's lifecycle table](/docs/guides/errors#order-lifecycle) for the full state-by-state breakdown.

## Compose

Assemble a recipient and content into something ready to price. There's no order yet — nothing here costs anything or touches USPS.

Content can come from raw `text` or a `pdf_url` on the API, the [composer at `/send`](https://sendpaperplane.com/send), a [template](/docs/guides/templates) pre-filled from the gallery, an [embedded widget](/docs/guides/embed) on someone else's site, a row from a [CSV import](/docs/guides/bulk-import), a [forwarded email](/docs/guides/email-to-send), or a [text (SMS) conversation](/docs/guides/imessage-to-send).

* **Endpoint** — none required yet; `GET /v1/address/autocomplete` helps fill in the recipient as they type (see [Addresses](/docs/guides/addresses)).
* **UI surfaces** — the `/send` composer, `template-embed.js` / `paperplane.js`, the CSV mapper (`POST /v1/csv-map`).

Go deeper: [Letter templates](/docs/guides/templates) · [Embed the send flow](/docs/guides/embed) · [Bulk sending](/docs/guides/bulk-import) · [Send by email](/docs/guides/email-to-send) · [Send by text](/docs/guides/imessage-to-send)

## Proof

Confirm what will actually print and what it will cost — before any money moves. Two things happen here, together:

1. **See the exact PDF.** The composer's "See the exact PDF before you pay" link renders the letter through the same `renderTextToPdf` the order path uses, so preview can never diverge from what mails.
2. **Price it and mint a `confirmation_token`.** `POST /v1/quotes` returns the all-in price plus a single-use, 30-minute token bound to the exact recipient, content, class, and price. On the agent surface, `POST /v1/orders` requires that token — a send can never be the first call.

* **Endpoint** — `GET /api/preview`, `POST /v1/quotes` (or the `quote_letter` MCP tool).
* **UI surface** — the composer's preview link.

Go deeper: [Preview before you pay](/docs/guides/print-preflight) · [Core concepts](/docs/concepts) for how confirmation tokens work

## Dispatch

Turn the proofed letter into a real, paid, mailed piece. `POST /v1/orders` does all of it in one call:

1. USPS verifies both addresses (correcting casing/formatting where needed).
2. Payment settles — a Stripe-hosted link the human approves, a prepaid credit code, or (sandbox) nothing at all.
3. Content is screened; a flagged letter goes to `held_for_review` instead of printing.
4. The print facility accepts it (`submitted`) and hands it to the carrier (`mailed`).

* **Endpoint** — `POST /v1/orders` (or `send_letter` over MCP).
* **UI surface** — the order page while payment or review is pending.

Go deeper: [Payments & confirmation](/docs/guides/payments) · [Address handling](/docs/guides/addresses) · [Error contract](/docs/guides/errors) for what can go wrong here

## Track

Once it's mailed, watch it move and step in if you still can.

* **Poll** `GET /v1/orders/{id}`, or pass `webhook_url` at order creation to get pushed on every transition instead.

* **Share** the public timeline at `/track/{trackingNumber}` — no login, safe to hand to the recipient or a lawyer.

* **Cancel** with `DELETE /v1/orders/{id}` and the order's `cancel_token`, while it's still `pending_payment`, `screening`, or `held_for_review`. Once `submitted`, it's in the pipe.

* **Review** with `POST /v1/reviews` and the `review_token`, once `delivered`.

* **Endpoint** — `GET /v1/orders/{id}`, `DELETE /v1/orders/{id}`, `POST /v1/reviews`.

* **UI surface** — the order page (private) and `/track/{trackingNumber}` (public).

Go deeper: [Cancel & track](/docs/guides/cancel-track) · [Delivery webhooks](/docs/guides/webhooks)