# Approver hierarchies and tiers

"Either regional director signs off, then the finance director, then we're done." Real approval chains mix alternatives ("either of these people") with requirements ("and then this person"), and they run in a defined order. The `approvers` field of an Approval Rule captures exactly this shape with a hierarchy of tiers.

## The shape of an approver hierarchy

The [ApproverHierarchy](/urn?urn=ctp%3Aapi%3Atype%3AApproverHierarchy) has three nested levels. Reading from the outside in:

- `tiers`: an ordered array of one to five tiers. **Every tier must be approved, in order**, for the hierarchy to complete.
- Within a tier, `and`: a list of groups that must **all** be satisfied (logical AND).
- Within a group, `or`: a list of approver roles where **any one** satisfies the group (logical OR).

Each leaf is a [RuleApprover](/urn?urn=ctp%3Aapi%3Atype%3ARuleApprover) pointing at an Associate Role. So the structure reads: all tiers, in order → all AND-groups in a tier → any one OR-approver in a group.

```mermaid
flowchart TD
	H[Approver hierarchy] -->|first| T1[Tier 1]
	H -->|then| T2[Tier 2]
	T1 --> A1["AND group: all required"]
	T1 --> A2["AND group: all required"]
	T2 --> A3["AND group: all required"]
	A1 --> R1["OR: any one Associate Role"]
	A2 --> R2["OR: any one Associate Role"]
	A3 --> R3["OR: any one Associate Role"]
```

The Associates overview in the API reference diagrams this structure alongside the end-to-end approval process; see [Intended workflow](/api/associates-overview.md#intended-workflow) for the full set of tier, conjunction, and disjunction visuals.

A hierarchy may have at most **five** tiers. If your governance needs more sequential stages than that, you are likely modeling an organizational process that belongs partly in an external system; revisit the requirement before trying to force it into the hierarchy.

## Building up the logic

Start simple and add only the structure you need.

**One approver.** A single role in one tier is the minimal hierarchy. Any holder of `apac-manager` approves.

```http
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/approval-rules HTTP/1.1
Content-Type: application/json

{
  "name": "Manager sign-off",
  "status": "Active",
  "predicate": "totalPrice > \"2000.00 AUD\"",
  "requesters": [ { "associateRole": { "typeId": "associate-role", "key": "apac-buyer" } } ],
  "approvers": {
    "tiers": [
      { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } } ] } ] }
    ]
  }
}
```

**AND/OR within one tier.** "Either regional director, and the compliance reviewer." Two AND-groups in one tier; the first group offers a choice of two directors.

```json
{
  "tiers": [
    {
      "and": [
        {
          "or": [
            { "associateRole": { "typeId": "associate-role", "key": "apac-director" } },
            { "associateRole": { "typeId": "associate-role", "key": "apac-deputy-director" } }
          ]
        },
        {
          "or": [
            { "associateRole": { "typeId": "associate-role", "key": "compliance-reviewer" } }
          ]
        }
      ]
    }
  ]
}
```

Here a director (either one) and a compliance reviewer must both approve, but they are in the **same tier**, so they can approve in any order relative to each other.

**Sequential tiers.** "Managers first, then the finance director." Two tiers, evaluated in order: the second tier does not open until the first is fully approved.

```json
{
  "tiers": [
    { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } } ] } ] },
    { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "finance-director" } } ] } ] }
  ]
}
```

## Design for approver absence

An approver hierarchy that names a single approver stalls the moment that person is on vacation, is reassigned, or is deactivated. Because approvers are Associate Roles rather than individuals, several people can hold the approving role, but a rule still blocks if no active holder is available. Design for absence from the start:

- **Assign approving roles to several people.** More than one holder of a role means any of them can clear the tier.
- **Use OR groups for interchangeable approvers.** An `or` of two roles, such as a director and a deputy director, lets either approve when the other is away.
- **Provide a higher-tier fallback.** A senior role, or a manager who also holds a routine approver's role, can step in when the usual approver is unavailable.

Governance that cannot be satisfied is worse than none, because it silently blocks legitimate orders. Build at least one backup path into every tier that would otherwise depend on one person.

## Tracking who is needed now

As a hierarchy progresses, the platform exposes which roles are still required in the currently active tier through the Approval Flow's `currentTierPendingApprovers` field. That field is what a buyer portal reads to notify the right people at each stage, and you will use it on the next page when tracing a live flow. Designing the tiers well here is what makes those notifications meaningful: each tier should correspond to a real decision point in the organization.

## Worked example: three Atlas approval shapes

Design approver hierarchies for three escalating Atlas APAC scenarios, all on top of the threshold predicates from the previous page.

1. **Routine spend (single approver).** Orders over AUD 2,000: one tier requiring `apac-manager`. Fast, single sign-off for everyday purchasing.
2. **Significant spend (AND/OR in one tier).** Orders over AUD 5,000: one tier where either `apac-director` or `apac-deputy-director` approves, and `finance-controller` approves. The OR gives cover when one director is unavailable; the AND guarantees finance always sees it.
3. **Strategic spend (sequential tiers).** Orders over AUD 50,000: tier one is the significant-spend tier above; tier two adds `finance-director` alone. The large deal must clear the same controls and then escalate to a final sign-off, in order.

Each design uses only as much structure as the decision needs, and never more than five tiers.

## Key takeaways

- An approver hierarchy is `tiers` (1–5, ordered) → `and` groups (all required) → `or` approvers (any one required); each leaf is an Associate Role.
- All tiers must approve in sequence; within a tier, AND-groups can be satisfied in any order.
- Use OR for interchangeable approvers (cover for absence) and AND for mandatory parallel approvers (such as finance plus a director).
- Design for approver absence: assign approving roles to several people, use OR groups for interchangeable approvers, and provide a higher-tier fallback so one person's absence cannot block an order.
- The active tier's outstanding roles surface as `currentTierPendingApprovers`, which drives stage-by-stage notifications.

## Related pages

- [Area overview page with navigation](/learning-model-b2b-commerce.md)
- [Previous page: Approval Rules: predicates and requesters](/learning-model-b2b-commerce/configure-approval-workflows/approval-rules-predicates-and-requesters.md)
- [Next page: Approval Flows in action](/learning-model-b2b-commerce/configure-approval-workflows/approval-flows-in-action.md)