Purchase orders
Cancel an order without deleting it
/a/PurchaseOrder_cancel
Set received status to Cancelled and retain the order and its data.
When to use this endpoint
Use the cancellation action rather than deletion when the record must remain visible to history and reporting. This is different from restoring a deleted order.
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. |
Example request
$result = FM_api('PurchaseOrder_cancel', [
'id'=>'1042',
]);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": "missing or invalid parameter: id"} | id integer-converts below 1. |
{"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. |
{"error": "Cannot cancel a Purchase Order that has started receiving"} | Received status is not Open or already Cancelled. |
{"error": "Cannot cancel a Purchase Order that has been sent"} | The open order has date_sent set. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Requires an existing visible order. Open unsent orders may be cancelled; receiving already started or a truthy date_sent causes an error. The direct status setter uses these same checks.
- An already-cancelled order is an idempotent no-op. Cancelling sets received status=4 and last_edited; it does not delete the record, reverse stock/receipts or clear approval, invoice metadata or sent history.
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 or the Purchase Orders list, choose Cancel. Detail-page checks are stricter than the API.
CRM2
CRM2 Purchase Orders has a Cancel action calling PurchaseOrder_cancel; the handler performs the same direct status update.
Related endpoints
PurchaseOrder_setStatus— Replace the numeric received status.PurchaseOrder_get— Read the current raw header.PurchaseOrder_restore— Recover a deleted order through the protected workflow.