Approvals
List Approval Policies
List the approval policy for every document type an approval policy can govern — purchase orders, vendor deposits and bill payments. A document type that was never configured is returned as an unsaved, disabled default (`id: null`, no tiers), so the response always has three entries.
List Approver Options
Search the users and roles that can be listed as approvers on a policy step. Returns up to 100 users (matched on name or email) followed by every matching role with its current member count.
List Approver Notifications
Whether each approver gets their approval alerts (Approval Requested, Approval Reminder, Approval Overridden) by email. Pass the users and roles on the policy (saved or not); role members are expanded. Reads the same per-user alert preferences each person manages under My notifications.
Update Approver Notifications
Turn approval-alert emails on or off for these approvers. Turning on sets email delivery to instant for Approval Requested, Approval Reminder and Approval Overridden; turning off leaves the chosen frequency. This writes each user's own alert preferences — they can still change it under My notifications.
Get Approval Policy
Get the approval policy for one document type. A type that was never configured returns a disabled default with no tiers.
Update Approval Policy
Replace the approval policy for one document type. The body is the complete policy — tiers, steps and approvers not sent are removed.
Preview Approval Routing
Route an amount through a policy without creating anything — answers 'who would have to approve this, and could the requester approve it themselves?'. Uses the saved policy, or an unsaved draft sent under `policy` so an edit can be checked before it is saved.
List Approval Requests
The approvals queue: paginated approval requests across purchase orders, vendor deposits and bill payments.
Get Pending Approval Count
Number of pending approval requests the signed-in user can act on right now (including requests they can act on as a delegate). Cached for up to 60 seconds; every decision clears the cache.
Bulk Approve Approval Requests
Approve several approval requests as the signed-in user. Each request is checked on its own: ones you are not eligible for, or that are no longer pending, are skipped with the reason — the rest are approved (for a multi-step request, your approval completes your step and the request moves on).
Get Document Approval
The approval state of one document: whether its policy is enabled, the request that currently governs it (the pending one, else the latest approved one) with full detail and your capabilities, every earlier request, and — when there is no current request — a routing preview of where an approval request for the document would go.
Get Approval Request
Get one approval request with its steps, every decision, who can act on each open step, and what the signed-in user may do with it.
Approve Approval Request
Approve the current step of a pending approval request. When this completes the last step the request becomes `approved` and the document moves on (a purchase order opens — and is sent to the supplier if that was requested — a vendor deposit or bill payment is approved). Otherwise the request advances to the next step and its approvers are notified.
Reject Approval Request
Reject a pending approval request at its current step. The request becomes `rejected`, the requester is notified with the reason, and the document stays unapproved (a purchase order stays in draft; an open purchase order awaiting re-approval keeps its changes flagged). The requester can amend the document and request approval again.
Withdraw Approval Request
Withdraw a pending approval request before anyone has approved it. The request becomes `withdrawn` and the document returns to its unrequested state. Once any approval has been recorded the request can no longer be withdrawn — an administrator can re-route it instead.
Send Approval Reminder
Send a reminder now to everyone who can act on the current step of a pending request. Separate from the policy's automatic reminders.
Override Approval Request
Complete a pending approval request as an administrator who is not an eligible approver — for example when nobody eligible is available. Every remaining step is marked approved, the request is flagged `overridden`, the decision is recorded as `override_approved` with your reason, and the requester and everyone who could have approved are notified.
Re-route Approval Request
Re-evaluate a pending approval request against the current policy — after the policy was edited, an approver left, or nobody is eligible. The original request is marked `superseded` (its `superseded_by_id` points at the new one) and a new pending request with reason `reroute` is returned. Approvals already given on a step whose approver list is unchanged carry over.
List Approval Delegations
List current and upcoming approval delegations (not revoked, not yet ended), earliest start first. Users see delegations they gave or received; administrators see everyone's, optionally narrowed with `user_id`.
Create Approval Delegation
Let someone approve on your behalf while you are away. During the window the delegate can act on every step you are eligible for; their decisions record `on_behalf_of` you. Pending requests are updated immediately.
Revoke Approval Delegation
Revoke a delegation immediately. Pending requests stop offering it to the delegate.
List Approval Queue
List order-approval requests awaiting the authenticated approver's decision at the current level.
List My Pending Approvals
List the authenticated buyer's own submitted approval requests still awaiting a decision.
Approve Order
Approve the current level of an approval request. When the final level approves, the request converts to a draft order (its id is returned) and the originating cart is emptied. Only an entitled approver for the current level may act.
Reject Order
Reject an approval request with a reason. The request returns to the buyer, who can edit and resubmit. A `reason` is required.