Cancel a purchase order

Cancels a purchase order, transitioning it to status: cancelled. Only orders that have NOT yet been received can be cancelled; partially or fully received orders must be closed via the Close Short workflow on the staff app. Any inventory quantities on order are released back to ATP via the canonical handler.

Separation of Duties (SoD) gate (NEW-GAP-PURCHASING-CANCEL-PERMISSION-SOD-PHASE-2 2026-05-16): Beyond the purchasing:write API-key scope, the user who created the API key (the on_behalf_of_user_id recorded on the key) MUST hold the purchasing.cancel permission key (granted by default to owner / admin / manager / accountant; staff / warehouse / sales / auditor / viewer denied). This mirrors Stripe’s restricted-keys design (destructive ops require their own scope), NetSuite’s “Cancel Order” capability (the API caller’s role must carry it), Acumatica’s “Cancel Order” form access rights, and AICPA SOX SoD framework (destructive financial actions require separate authorization from creation). A 403 permission_denied response is returned when the key’s owning user lacks the RBAC; the denied attempt is recorded in the activity log (SoC2 CC6.1 + PCAOB AS 2201 §17).

Requires purchasing:write API-key scope AND the key-creator’s user role must carry purchasing.cancel.