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-Keystring

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. The body's idempotency_key takes precedence over this header.

Request body

messagestring required

Letter body. Supports {{first_name}}/{{last_name}}/{{greeting}} merge fields.

skip_invalidboolean
no_return_address_ackboolean

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_keystring

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

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

order_idstring

Order UUID; test_<uuid> for a test-mode key (nothing is created)

statusstring

paid, pending_payment, … or test

letter_countinteger
total_centsinteger
tracking_urlstring uri nullable
checkout_urlstring uri nullable
idempotent_replayboolean

Present (true) when this is the original order returned for a repeated idempotency key

testboolean

Present (true) for a test-mode key: validated and priced, nothing created or charged

skipped_recipientsinteger

Changes

No recorded changes to this operation across all 1 revision of this API.