Email a purchase order to the vendor (first send or revision send)
Sends the purchase order to the vendor by email through the canonical
sendDocument helper (THE ONE RULE for document emails), stamps
sent_at on the order row, and syncs last_notified_revision to the
current revision_count so any amber revision banner on PO detail
clears.
Three send modes are supported:
- First send (default): no
template_key_overrideset. Uses the default purchase-order template and broadcastspurchase_order.sent. - Revision send: set
template_key_override='po_revised'plusrevision_numberandchanged_fieldsso the vendor receives the dedicated revision template; broadcastspurchase_order.revised_sent. Used by the revision-notification prompt’s “Send” path — the “Skip” path is handled byPOST /purchase-orders/{id}/notify-revision. - Stamp-only: set
stamp_only=trueto recordsent_atwithout emitting an email (the email has already been sent through a separate path, e.g. the dashboard’s “Email to Vendor” dialog).
Guards:
- 422
po_pending_approvalif the PO is awaiting approval. - 422
po_cancelledif the PO is cancelled. - 422
vendor_email_missingif noto_emailis provided AND the vendor account has no email on file (skipped whenstamp_only=true).
Side effects: stamps sent_at + last_notified_revision, emits a
purchase_order.sent (or purchase_order.revised_sent) broadcast
(Rule 13), and writes a po_sent (or po_revised_vendor_notified)
activity entry (Rule 20).
Rule 25: this endpoint is wired in both the API-key dispatch and the Cognito-JWT dispatch — API key callers and dashboard callers reach the same canonical handler.
purchasing:writeAuthorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Optional idempotency key for safe retries (Stripe-style).
255Path Parameters
Body
Override the destination email. When omitted, defaults to
the vendor account's email. Required (either here or on
the vendor) unless stamp_only=true.
When true, stamps sent_at + last_notified_revision
without dispatching an email (the email has already been
sent through a separate path). Skips the to_email /
vendor-email guard.
When set to po_revised, uses the revision-send template
instead of the default purchase-order template. Combine
with revision_number and changed_fields for context.
po_revised The revision number being sent (e.g. 2 for the second
send after the initial first-send 1). Used only when
template_key_override='po_revised'.
Human-readable summary of what changed between revisions
(e.g. "line quantity, due date"). Rendered in the revision
email template. Used only when
template_key_override='po_revised'.
Response
Purchase order sent (or stamped). Returns the canonical send result.

