> ## 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.

# Sandbox mode

> Run the entire send flow for free, instantly, with no keys and no real mail.

## What sandbox does

Pass `sandbox: true` anywhere you create an order. paperplane runs the **complete** pipeline — document rendering, pricing, address verification, content screening, and simulated fulfillment with a mock tracking number — instantly and free. Nothing is mailed and no card is charged.

<Note>
  Sandbox is the fastest way to test the whole product before a real card or real mail is involved. Agents can complete a full flow on their first call, before any human signs up for anything.
</Note>

## A sandbox order

The order is created already `submitted` with a mock tracking number:

```bash theme={null}
curl -X POST https://sendpaperplane.com/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "mail_class": "first_class",
    "sandbox": true,
    "text": "This is a test letter.",
    "to":   { "name": "Ada Lovelace", "line1": "1 Analysis Way",
              "city": "San Francisco", "state": "CA", "zip": "94107" },
    "from": { "name": "Justin", "line1": "2 Test St",
              "city": "Oakland", "state": "CA", "zip": "94612" }
  }'
```

```json theme={null}
{
  "status": "ok",
  "order": {
    "id": "ord_test_2ea2f33a74206e2d",
    "status": "submitted",
    "sandbox": true,
    "tracking_number": "9400MOCK00000001",
    "price_cents": 199
  },
  "capability": {
    "cancel_token": "ppc_...",
    "review_token": "ppc_..."
  }
}
```

## What's real vs simulated

| Piece                       | Sandbox              | Live                      |
| --------------------------- | -------------------- | ------------------------- |
| Document render + screening | Real (same code)     | Real                      |
| Address verification        | Real (same code)     | Real                      |
| Payment                     | Skipped              | Stripe link / credit code |
| Printing + mailing          | Simulated            | Real provider             |
| Tracking number             | Mock (`9400MOCK...`) | Real USPS                 |

<Warning>
  Sandbox orders are **not** persisted across redeploys and intentionally don't fire outbound delivery webhooks (they bypass the provider pipeline).
</Warning>

## Testing cancellation & reviews

Sandbox orders are created `submitted`, so they're past the cancelable window (`too_late`, 409) — the same as a live order that's already been handed to the carrier. To test a successful **cancel**, you need an order in a cancelable state; the capability-token gating is what you're really testing.

You **can** review a sandbox order (it's in a reviewable state), attributed from your return address.

## Credit codes and sandbox orders

`POST /v1/credits/checkout` has no sandbox mode — it always requires Stripe
configured (`STRIPE_SECRET_KEY`) and fails `503 payments_not_configured`
without it, sandbox or not. `GET /v1/credits/{code}` is a plain lookup with
no sandbox awareness either: a code has to actually exist to return a
balance.

What sandbox **does** change is what happens to a `credit_code` you pass on
a sandbox order: because sandbox orders skip payment entirely, the code is
never authorized or debited — any value, including one that doesn't exist,
is accepted and ignored. Don't rely on that to test real credit redemption;
test the redemption path against a real (test-mode Stripe) credit code
instead.