Skip to main content
POST

Headers

Idempotency-Key
string

Any unique string. Retrying with the same key returns the original order instead of creating a duplicate.

Maximum string length: 120

Body

application/json
to
object
required

Recipient address Use recipients instead to send to several people.

from
object
required

Return address. It may be outside the US: set country. For a US address (no country, or US), state and zip are required and follow the US rules; elsewhere state is the region and zip the postcode, both optional.

content
object
required
customer_email
string<email>
idempotency_key
string

With recipients, a retry with the same key returns the same batch.

certified
enum<string>
default:none

USPS Certified Mail. certified ($14.99): tracking number and proof of mailing and delivery. certified_return_receipt ($19.99): adds the recipient's signature. none ($4.99): regular First-Class.

Available options:
none,
certified,
certified_return_receipt
express
boolean
default:false

USPS Priority Mail (2-3 days, tracked); not with certified.

recipients
object[]

Send the same postcard or letter to several people: 2–25 addresses, used instead of to. Each recipient becomes its own order (own review, tracking and refund), grouped into a batch that is paid with one checkout link. The response is a Batch, not an Order.

Required array length: 2 - 25 elements

Response

Idempotency-Key already used: the original order is returned (a Batch when the request used recipients)

id
string
Example:

"ord_8k2m4qz7c1x9b3vd"

object
enum<string>
Available options:
postcard,
letter
product
enum<string>
Available options:
postcard_4x6,
postcard_6x9,
postcard_6x11,
letter,
letter_certified,
letter_certified_rr
status
enum<string>
Available options:
awaiting_payment,
paid,
printing,
mailed,
cancelled,
refunded
status_detail
string
price
object
to
object

A US address (recipients are always in the US, including territories and APO/FPO/DPO).

from
object

Return address. It may be outside the US: set country. For a US address (no country, or US), state and zip are required and follow the US rules; elsewhere state is the region and zip the postcode, both optional.

content
object
checkout_url
string | null

Where the person pays. Null once paid or closed. Never expires.

order_url
string

Human-readable status page

preview_url
string

Exact print preview

created_at
string<date-time>
paid_at
string<date-time> | null
mailed_at
string<date-time> | null
events
object[]
certified
enum<string>

Letters only: the USPS extra service.

Available options:
none,
certified,
certified_return_receipt
tracking
object | null

USPS tracking once the piece is accepted (certified letters always get one).

batch_id
string | null

Set when the order is part of a batch (created with recipients). Its checkout_url is then the batch's single payment link.