Skip to main content

Update Approval Policy

PUT 
/api/approval-policies/:documentType

Replace the approval policy for one document type. The body is the complete policy — tiers, steps and approvers not sent are removed.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token with the purchase-orders scope (read for GET, write for POST/PUT/DELETE).

Requires permission: approval_policies.manage

Body fields:

  • enabled (boolean, required)
  • separation_of_duties (string, required) — allow_if_sole_approver | strict | off
  • reminder_interval_hours (integer 1–720, optional, nullable) — null turns automatic reminders off
  • reminder_max (integer 0–10, optional, default 3)
  • reapproval_tolerance_percent (number 0–100, optional, default 0)
  • applies_to_sources (array of strings, optional, nullable) — purchase order policies only; each value must be a governable source (manual, import, auto_reorder, forecast, unified_plan, dropship). Null uses the default set.
  • tiers (array, required, max 10) — ordered smallest band first:
    • tiers.*.name (string, required, max 120)
    • tiers.*.up_to_amount (number, nullable, min 0.01) — base-currency upper limit; must increase tier by tier; only (and always) the last tier is null
    • tiers.*.requires_approval (boolean, required) — false auto-approves the band
    • tiers.*.steps (array, required — send [] for an auto-approve tier, max 3) — sequential steps:
      • tiers.*.steps.*.name (string, required, max 120)
      • tiers.*.steps.*.required_approvals (integer 0–20, required) — with only users listed it cannot exceed the number of users
      • tiers.*.steps.*.distinct_from_previous_steps (boolean, optional, default false)
      • tiers.*.steps.*.approvers (array, required, max 50) — at least one when the tier requires approval; no duplicates
        • tiers.*.steps.*.approvers.*.type (string, required) — user | role
        • tiers.*.steps.*.approvers.*.id (integer, required) — a user or role in this account
  • reroute_pending (boolean, optional, default false) — when the saved policy is enabled, re-evaluate every pending request against the new tiers (approvals on unchanged steps carry over)

Side effects: turning an enabled policy off withdraws its pending requests; the affected documents fall back to their pre-policy behaviour. The change is written to the activity log.

Returns 422 with field-keyed errors when the policy is invalid (for example, enabling a policy with no tiers, limits that do not increase, an empty approver list, an approver no longer in the account, or a non-governable source).

Request​

Responses​

OK

Response Headers
    Content-Type