---
title: "Create (and pay for) a new order"
method: POST
path: "/api/v1/orders"
---

# Create (and pay for) a new order

`POST /api/v1/orders`

## Request

- Base URL: `https://www.premierletters.com`
- URL: `https://www.premierletters.com/api/v1/orders`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- OrderCreate
  - `message` string, required: Letter body. Supports {{first_name}}/{{last_name}}/{{greeting}} merge fields.
  - `recipients` Recipient[]
    - `first_name` string
    - `last_name` string
    - `address_line1` string
    - `address_line2` string
    - `city` string
    - `state` string: Two-letter US state code
    - `zip` string
    - `custom_fields` object
  - `options` OrderOptions
    - `handwriting_style` string: Font UUID from GET /api/v1/styles
    - `paper_type` 'standard' | 'premium'
    - `product_type` string: e.g. letter, card, postcard
    - `authenticity_preset` string
    - `mailing_option` 'we_mail' | 'you_mail_stamped' | 'you_mail_no_stamp': Delivery option. Omit to use the account's default mailing option (else we_mail).
    - `include_letter` boolean
    - `include_envelope` boolean
    - `copies` integer: Values above 1 only for ship-to-you mailing options
    - `output_mode` 'handwritten' | 'printed_bw' | 'printed_color': How the letter body is produced: pen-written (default) or printed in black & white / color.
    - `envelope_output_mode` 'printed_bw' | 'printed_color' | 'null', nullable: How the envelope is produced: null (default) = hand-addressed, or printed. Independent of output_mode.
  - `payment` object
    - `method` 'card_on_file' | 'checkout_session' | 'balance': balance pays from the prepaid balance and waives the small-order handling fee (orders under 5 pieces); 402 insufficient_balance when short.
    - `return_url` string, uri
  - `skip_invalid` boolean
  - `return_address` ReturnAddress: Return address written on the envelope. Omit to use the account default (Settings). Required for an envelope order unless the account has a default or no_return_address_ack is true. name, address_line1, city, state and zip are required unless return_address_partial_ok is true (then at least one of name, company, address_line1, city, state, zip, printed as written).
    - `name` string
    - `company` string
    - `address_line1` string
    - `address_line2` string
    - `city` string
    - `state` string: Two-letter US state code
    - `zip` string: 5-digit ZIP or ZIP+4
  - `return_address_partial_ok` boolean: Send return_address exactly as written although it is incomplete: at least one of name, company, address_line1, city, state, zip. Only the filled lines print (a name alone is fine). Without it an incomplete return_address is refused.
  - `no_return_address_ack` boolean: Send with no return address at all. Only honoured when no return_address is given and the account has no default; undeliverable mail is then destroyed. Without it, such an order is a 400 no_return_address_unacknowledged.
  - `idempotency_key` string: Client-supplied key, 1-255 characters. A repeat with the same key and the same body returns the original order (200, idempotent_replay: true) instead of creating a second one. The same key with a different body is a 422 idempotency_key_reused; a repeat while the first request is still running is a 409 idempotency_in_progress. Also accepted as the Idempotency-Key header; the body wins.

## Response `200`

Idempotent replay: the order already created with this key (idempotent_replay: true)

- Order
  - `order_id` string: Order UUID; test_<uuid> for a test-mode key (nothing is created)
  - `status` string: paid, pending_payment, … or test
  - `letter_count` integer
  - `total_cents` integer
  - `tracking_url` string, uri, nullable
  - `checkout_url` string, uri, nullable
  - `return_address` object
    - `source` 'request' | 'profile' | 'none': Which return address the envelope uses: the request, the account default, or none (acknowledged).
  - `idempotent_replay` boolean: Present (true) when this is the original order returned for a repeated idempotency key
  - `test` boolean: Present (true) for a test-mode key: validated and priced, nothing created or charged
  - `skipped_recipients` integer

## Other responses

- `201`: Order created and paid, or (test key) validated and priced with test: true
- `202`: Order created, payment pending (checkout_url returned)
- `400`: no_return_address_unacknowledged (envelope order with no return_address, no account default and no no_return_address_ack), invalid_payment_method, payment_method_not_supported, invalid_delivery, content_not_allowed
- `402`: Payment required or failed (no_payment_method, payment_failed, insufficient_balance)
- `409`: idempotency_in_progress: a request with this idempotency key is still being processed; retry shortly
- `422`: validation_failed, or idempotency_key_reused (same key, different request body)
- `429`: Rate limited
- `502`: checkout_unavailable: nothing created, safe to retry

## Changes

- **2026-10-20** `9dc302324ca1`: 6 info
  - added the new optional request property `return_address_partial_ok`
  - the request property `return_address/address_line1` became optional
  - the request property `return_address/city` became optional
  - the request property `return_address/name` became optional
  - …2 more

[Operation history](https://skmtc.dev/premierletters/apis/premier-letters-api/changes/api/v1/orders/post.md)

---

[API](https://skmtc.dev/premierletters/apis/premier-letters-api.md) · [All operations](https://skmtc.dev/premierletters/apis/premier-letters-api/llms.txt) · [OpenAPI document](https://skmtc.dev/premierletters/apis/premier-letters-api/revisions/9dc302324ca1?raw)