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_override set. Uses the default purchase-order template and broadcasts purchase_order.sent.
• Revision send: set template_key_override='po_revised' plus revision_number and changed_fields so the vendor receives the dedicated revision template; broadcasts purchase_order.revised_sent. Used by the revision-notification prompt’s “Send” path — the “Skip” path is handled by POST /purchase-orders/{id}/notify-revision.
• Stamp-only: set stamp_only=true to record sent_at without emitting an email (the email has already been sent through a separate path, e.g. the dashboard’s “Email to Vendor” dialog).
• External (mark as sent): set send_mode=external when the vendor was contacted OUTSIDE Arcus (phone / the buyer’s own email). The PO is advanced to sent (draft -> open, sent_at stamped) in the SAME atomic transaction as the email path, but Arcus dispatches no email and writes no communication log row. Audited as po_marked_sent_external (not po_sent). The vendor-email guard is skipped. Useful for drop-ship POs where sending unlocks recording the vendor’s direct shipment.

Guards:

• 422 po_pending_approval if the PO is awaiting approval.
• 422 po_cancelled if the PO is cancelled.
• 422 vendor_email_missing if no to_email is provided AND the vendor account has no email on file (skipped when stamp_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, or po_marked_sent_external when send_mode=external) 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.

Required API key scope: purchasing:write

POST /purchase-orders/{id}/send-to-vendor

Email a purchase order to the vendor (first send or revision send)

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to_email": "[e-mail]",
  "stamp_only": false,
  "send_mode": "email",
  "template_key_override": "po_revised",
  "revision_number": 123,
  "changed_fields": "<string>"
}
'

import requests

url = "https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor"

payload = {
    "to_email": "[e-mail]",
    "stamp_only": False,
    "send_mode": "email",
    "template_key_override": "po_revised",
    "revision_number": 123,
    "changed_fields": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to_email: '[e-mail]',
    stamp_only: false,
    send_mode: 'email',
    template_key_override: 'po_revised',
    revision_number: 123,
    changed_fields: '<string>'
  })
};

fetch('https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'to_email' => '[e-mail]',
    'stamp_only' => false,
    'send_mode' => 'email',
    'template_key_override' => 'po_revised',
    'revision_number' => 123,
    'changed_fields' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor"

	payload := strings.NewReader("{\n  \"to_email\": \"[e-mail]\",\n  \"stamp_only\": false,\n  \"send_mode\": \"email\",\n  \"template_key_override\": \"po_revised\",\n  \"revision_number\": 123,\n  \"changed_fields\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to_email\": \"[e-mail]\",\n  \"stamp_only\": false,\n  \"send_mode\": \"email\",\n  \"template_key_override\": \"po_revised\",\n  \"revision_number\": 123,\n  \"changed_fields\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/purchase-orders/{id}/send-to-vendor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to_email\": \"[e-mail]\",\n  \"stamp_only\": false,\n  \"send_mode\": \"email\",\n  \"template_key_override\": \"po_revised\",\n  \"revision_number\": 123,\n  \"changed_fields\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "po_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "sent_to": "[e-mail]",
  "sent_at": "2023-11-07T05:31:56Z",
  "revision_send": true,
  "revision_number": 123
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

"<unknown>"

"<unknown>"

Authorizations

Authorization · string · header · required

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

Idempotency-Key · string

Optional idempotency key for safe retries (Stripe-style).

Maximum string length: 255

Path Parameters

id · string<uuid> · required

Body

application/json

to_email · string<email>

Override the destination email. When omitted, defaults to the vendor account's email. Required (either here or on the vendor) unless stamp_only=true.

stamp_only · boolean · default: false

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.

send_mode · enum<string> · default: email

email (default) sends the vendor an email via the canonical sendDocument helper. external marks the PO as sent WITHOUT dispatching an email (the vendor was contacted outside Arcus) -- same atomic draft->open + sent_at stamp + broadcast, no communication log row, audited as po_marked_sent_external, and the vendor-email guard is skipped. Mutually independent of stamp_only; both skip the email dispatch.

Available options: email, external

template_key_override · enum<string>

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.

Available options: po_revised

revision_number · integer

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'.

changed_fields · string

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

200

application/json

Purchase order sent (or stamped). Returns the canonical send result.

po_id · string<uuid>

po_number · string

sent_to · string<email>

sent_at · string<date-time>

revision_send · boolean

Present and true only when template_key_override='po_revised'.

revision_number · integer

Echoes the request body when this was a revision send.