Approval chains

Who approves purchase orders and invoice payments.

More about this resource

Configures who approves purchase orders and invoice payments - separate from Settlement's autonomy settings, which control whether a person is needed at all rather than which person. Each of the two processes (purchase_order, invoice_payment) has one approval flow, under Workflows in Pleaxy, or is linked to share the other process's flow. A flow is an ordered list of groups, run one after another. A sequential group is one step with one approver; a parallel group is several steps that must all be approved, in any order, by different people. A group with conditions runs only when every condition matches the document (amount, supplier or requester); a step marked highValueOnly runs only when the amount is above Settlement's approvalThreshold. Every step names a specific employee, and only that employee can act on it. A new region starts with one step, 'Region administrator'. When a PO or invoice is created, its chain is a point-in-time snapshot of the flow, so editing the flow later doesn't change documents already waiting.

Endpoints

GET…/approval-chains/{process}
PATCH…/approval-chains/{process}

Get approval chain settings

Returns the approval flow for a process.

GET/v1/workspaces/{regionId}/approval-chains/{process}

Parameters

process"purchase_order" | "invoice_payment"Required
Which flow's approval chain to fetch.

Returns

200 OK with the object shown in the response.

More details

Returns the approval flow for a process, or { process, groups: [] } if the process has never had one. Accepts a buyer API key.

Response fields

linkedTo"purchase_order" | "invoice_payment"
When set, this process uses the other process's flow (a live link, not a copy), and groups is ignored.
groups[].mode"sequential" | "parallel"
sequential: exactly one step. parallel: every step must be approved, in any order, each by a different employee.
groups[].conditionsarray
When present, the group runs only if every condition matches. amount uses gt, gte, lt or lte with a number in the region's currency; supplier uses is or is_not with a supplier Workspace ID (ending in .supplier); requester uses is or is_not with an employee key. A document in another currency than the region's meets every amount condition.
groups[].stages[].approverEmployeeKeystring
The only employee who can act on the step. '' means the step has no approver yet - it needs one assigned before anyone can act on it. Only a flow saved before named approvers were required can carry it.
groups[].stages[].highValueOnlyboolean
The step runs only when the amount is above Settlement's approvalThreshold (the high-value threshold).
source"default"
Present when Pleaxy wrote this flow as the region's default. Any other save clears it.
defaultApproverIsAdminboolean
Only with source "default": whether the default step's approver is still a region administrator.
requesterRule.eligibleApproverCountnumber
How many buyer members can approve this process's documents. A requester can approve their own document only when nobody else could.

Errors

401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.

GET /v1/workspaces/{regionId}/approval-chains/{process}

Request

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/approval-chains/{process}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 200 OK

{
   "process": "purchase_order" | "invoice_payment",
   "linkedTo": "purchase_order" | "invoice_payment",
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            {
               "id": "string",
               "label": "string",
               "approverEmployeeKey": "string",
               "approverName": "string",
               "approverEmail": "string",
               "highValueOnly": boolean
            }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ],
   "source": "default",
   "defaultApproverIsAdmin": boolean,
   "requesterRule": { "eligibleApproverCount": number }
}

Update approval chain settings

Replaces the approval flow for a process.

PATCH/v1/workspaces/{regionId}/approval-chains/{process}

Parameters

process"purchase_order" | "invoice_payment"Required
Which flow's approval chain to update.

Body

groupsarray
The new flow, in order. Each { id, mode, label?, stages, conditions? }. stages are { id, label, approverEmployeeKey, highValueOnly? }: a sequential group has exactly one, a parallel group at least one, with unique ids and different approvers. Up to 10 conditions per group. At least one group.
linkedTo"purchase_order" | "invoice_payment"
Use the other process's flow instead of this one's own.
useDefaulttrue
Reset to the region default: one step, 'Region administrator', naming the region's owning administrator, or else the first administrator by name. Can't be combined with groups, stages or linkedTo.
stagesarray
Legacy flat shape, one sequential step per entry, { id, label, approverEmployeeKey, highValueOnly? }. Saved as the equivalent groups.

Returns

200 OK with the object shown in the response.

More details

Replaces a process's flow with groups, links it to the other process's flow with linkedTo, or resets it to the region default with useDefault: true. Sending groups clears any linkedTo; sending linkedTo keeps the current groups on record but inactive while the link holds. Each approverEmployeeKey is checked against the workspace's employees. The flow must keep at least one group with no conditions that runs for ordinary amounts, so every document reaches a person. stages, a flat list of single-step groups, is still accepted for older clients; prefer groups.

Changed 2026-09-27, a security fix inside v1: Signed-in session only, for every process: an approval chain decides who approves spend, so an API key gets 403 HUMAN_SESSION_REQUIRED whatever its procurement role.

Errors

400 Bad Request - A step has no approver ("'{label}' has no approver - every approval step must name a specific employee.") or names someone who isn't an employee of the workspace; a parallel group names the same approver twice; a sequential group doesn't have exactly one step; a condition is malformed; the flow has no group with no conditions that runs for ordinary amounts ("A chain needs at least one approval step with no conditions that applies to ordinary purchase amounts…"); groups or stages is empty; linkedTo names this process, or a process already linked back to it; or useDefault is combined with groups, stages or linkedTo.
409 Conflict - Code NO_REGION_ADMIN, with useDefault: "This region has no administrator to route approvals to. Make someone an administrator first."
403 Forbidden - Code HUMAN_SESSION_REQUIRED. The caller isn't a signed-in person (for example, an API key), for any process ("Approval chains can only be changed by a signed-in person. Change them in Pleaxy."). Nothing is saved.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.

PATCH /v1/workspaces/{regionId}/approval-chains/{process}

Request

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/approval-chains/{process}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "highValueOnly": boolean }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ]
}

Response · 200 OK

{
   "process": "purchase_order" | "invoice_payment",
   "linkedTo": "purchase_order" | "invoice_payment",
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            {
               "id": "string",
               "label": "string",
               "approverEmployeeKey": "string",
               "approverName": "string",
               "approverEmail": "string",
               "highValueOnly": boolean
            }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ],
   "source": "default",
   "defaultApproverIsAdmin": boolean,
   "requesterRule": { "eligibleApproverCount": number }
}