Skip to main content

​
What credits are

Credits are a prepaid balance that pays for letters. POST /v1/orders with a credit_code redeems from the balance instead of charging a card. There’s no account to manage — the code is the balance.

​
The two-part balance (CARD Act)

Under the federal CARD Act, purchased stored value must stay spendable for at least 5 years. Several states are stricter. So a credit account splits into two buckets: GET /v1/credits/{code} returns both, plus spendable:
balance_cents is the total spendable now (face_cents + unexpired bonus_cents) — the number to show a caller checking their balance.

​
Buying credits

POST /v1/credits/checkout creates a checkout session. The credit code is emailed once payment settles, regardless of which mode created the session. By default (checkout_ui_mode: "hosted", or the field omitted entirely) it returns a hosted checkout URL (a paperplane payment link) to redirect to:
Pass checkout_ui_mode: "embedded" and it instead returns an embedded-checkout payment_client_secret to mount in place with initEmbeddedCheckout — for a page (like paperplane’s own /embed widget) that can’t redirect or open a new tab. The response is a discriminated union keyed on checkout_ui_mode: exactly one of payment_url / payment_client_secret is ever present, and the field itself says unambiguously which:
POST /v1/credits/checkout always requires payments to be configured — there is no sandbox flag on this endpoint, and it fails closed with 503 payments_not_configured if STRIPE_SECRET_KEY is unset, regardless of what else the deployment is doing in sandbox. A credit_code on a sandbox order, by contrast, is never actually charged or even looked up — sandbox orders skip payment entirely, so any code (real, fake, or omitted) is accepted. See Sandbox mode.

​
Codes

  • Format pp-xxxx-xxxx-xxxx, case-insensitive (we lower-case on input).
  • Redeemed at order creation — pass credit_code alongside your letter.

​
When to prefer credits

  • High-volume or recurring senders who don’t want a card prompt per letter.
  • Budget controls — top up a fixed amount and it can’t be exceeded.
  • Gifting or distributing “send N letters” to other people.
Last modified on September 28, 2026