Sandbox mode

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.

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.

A sandbox order

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

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" }
  }'

{
  "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

Sandbox orders are not persisted across redeploys and intentionally don’t fire outbound delivery webhooks (they bypass the provider pipeline).

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.

Get started

Guides

Tutorials

What sandbox does

A sandbox order

What’s real vs simulated

Testing cancellation & reviews

Credit codes and sandbox orders

​What sandbox does

​A sandbox order

​What’s real vs simulated

​Testing cancellation & reviews

​Credit codes and sandbox orders

What sandbox does

A sandbox order

What’s real vs simulated

Testing cancellation & reviews

Credit codes and sandbox orders