Create or reuse an x402 machine order

Unauthenticated calls return 402 Payment Required when the order is ready to be paid. Retry the exact same body with PAYMENT-SIGNATURE after settlement. A 202 settled_pending_webhook response means Stripe is verifying the transaction; poll status and do not pay again.

post/api/machine/orders

Request

  • Base URL: https://postalform.com
  • URL: https://postalform.com/api/machine/orders
  • Auth: none required

Request body

OR

Response

Existing machine order is already paid

checkout_urlstring uri nullable

Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link.

status_urlstring uri

Poll this same order after either payment path.

page_countnumber nullable
next_action'choose_payment_method' | 'open_checkout' | 'poll_status'
order_idstring uuid required

Canonical server order id. This may differ from request_id when PostalForm reuses an existing unpaid draft.

statusstring required
payment_statusstring required
is_paidboolean required
current_stepstring nullable required
payment_intent_idstring nullable required
payment_channelstring nullable required
currencystring nullable required
mailpiece_type'letter' | 'postcard' required
postcard_size'4x6' | '6x9' | '11x6' nullable required
postcard_guidelines_urlstring uri nullable required

Canonical postcard PDF formatting guide. Present for postcard responses and null for letter responses.

certifiedboolean
certified_return_receiptboolean
return_receipt_format'electronic' | 'physical'
restricted_deliveryboolean
err_delivery'manual' | 'email'
err_emailstring email nullable
err_status'manual' | 'pending' | 'sent' | 'failed'
err_document_availableboolean
err_delivered_atstring date-time nullable
tracking_numberstring nullable
tracking_urlstring uri nullable
usps_tracking_urlstring uri nullable
campaign_urlstring nullable

Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders.

Changes

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