Save delivery contact and instructions

When to use this endpoint

Use when saving the delivery-detail section. Send all three values; omitted values are errors rather than a partial update.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use dispatcher CSRF protection when configured.

Requires explicit View on Purchase Order or Purchase Orders. Writes also require the matching Edit permission; clearing invoice details requires Delete. A non-administrator blocked by the legacy Purchase Orders visibility flag (crm_access bit 256) is denied. API keys use their owner’s permissions.

The primary order is checked against the current tenant and Purchase Order record scope. Configured TeamAccess follows permitted linked Contracts, Customers, Jobs, Quotes and Departments; the legacy department filter follows direct Customer/Quote/customer-Job links. An inaccessible or missing order returns purchase order does not exist.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible	Yes	Positive local Purchase Order ID/digit string; not the displayed po_num. Missing, malformed or inaccessible IDs fail.
`delivery_address`	String	Yes	Required by presence; blank clears this field. Stored without date/address parsing or trimming.
`instructions`	String	Yes	Required by presence; blank clears this field. Stored without date/address parsing or trimming.
`attention`	String	Yes	Required by presence; blank clears this field. Stored without date/address parsing or trimming.

Example request

$result = FM_api('PurchaseOrder_setDeliveryDetails', [
	'id'=>'1042',
	'delivery_address'=>'12 Harbour Road',
	'instructions'=>'Use the goods entrance',
	'attention'=>'Stores team',
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error": "no ID provided"}`	id absent/null.
`{"error": "no address provided"}`	delivery_address absent/null.
`{"error": "no instructions provided"}`	instructions absent/null.
`{"error": "no attention provided"}`	attention absent/null.
`{"error": "permission denied"}`	The required page/action or legacy visibility setting denies access.
`{"error": "purchase order does not exist"}`	The primary order is missing or outside the caller’s permitted scope.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

All three strings are required; blank clears the corresponding value. They replace attention, delivery_address and instructions together.
The target, expected delivery date, supplier and totals remain unchanged. This is not a notification-recipient or mail operation.

Side effects

Header writes lock the existing order and tenant owner, check persistence and record history in the same transaction. Errors roll back the header and audit; a true no-op returns {ok:1,warning:"no change needed"} without a new event/history entry. Cache invalidation and edit-event follow-ups run after the owning transaction commits; an event exception returns saved=1 and a no-replay warning.
A changed header emits PurchaseOrder_edit after commit; configured account listeners may perform integration work. No order email/PDF is sent directly by this route.

See it in Fieldmotion

CRM1

In CRM1 Purchase Order details, change Delivery Attention, Address or Instructions. Each field change sends all three values to PurchaseOrder_setDeliveryDetails.

CRM2

No direct caller was found in CRM2 source. Its Purchase Order screen uses mapped reads and generic field saves rather than this legacy endpoint.

Related endpoints

PurchaseOrder_setDeliveryAddress — Save the selected address.
PurchaseOrder_setDeliveryDate — Set the expected delivery date.