# Advanced Partner Hierarchy

Most integrations do not need to manage the full partner hierarchy directly. Use this reference when Bead instructs you to create or manage ISO, Agent, Corporate Entity, or Master Merchant partner records.

For most partners, the common operating model is:

```
Partner → Merchant → Location → Terminal → Payment
```

Some larger ISO, super-ISO, reseller, or boarding-platform programs require additional partner records before merchants are created. In those cases, merchants ultimately roll up under a Master Merchant partner record.

### Key rule

Every partner hierarchy branch must resolve to a Master Merchant record.

When a partner is created at the ISO, Agent, or Corporate Entity level, Bead automatically creates the downstream sub-partner records required to reach a Master Merchant.

| Partner record created | Downstream records automatically created by Bead     |
| ---------------------- | ---------------------------------------------------- |
| ISO                    | Agent, Corporate Entity, Master Merchant             |
| Agent                  | Corporate Entity, Master Merchant                    |
| Corporate Entity       | Master Merchant                                      |
| Master Merchant        | No additional partner hierarchy records are required |

For example, when an ISO partner is added, Bead creates the ISO and automatically creates an Agent, Corporate Entity, and Master Merchant under it. You do not need to separately add each downstream level.

### Partner hierarchy

```
ISO
 └─ Agent
    └─ Corporate Entity
       └─ Master Merchant
          └─ Merchant
             └─ Location
                └─ Terminal
                   └─ Payment
```

### Partner types

| Partner type             | API value         | Typical use                                                     |
| ------------------------ | ----------------- | --------------------------------------------------------------- |
| ISO                      | `iso`             | Top-level ISO or super-ISO organization.                        |
| Agent                    | `agent`           | Regional office, sales group, or sub-organization under an ISO. |
| Corporate Entity / Corp  | `corporateEntity` | Business or legal entity layer under an Agent.                  |
| Master Merchant / Master | `masterMerchant`  | Required partner-level record that merchants are created under. |

### Multiple Agents under an ISO

Large ISO or super-ISO relationships may have multiple Agent records under the same ISO. Agent records often represent regional offices, business units, or similar operational groupings.

Example:

```
ISO: Acme Payments
 ├─ Agent: Acme Payments
 ├─ Agent: Acme Payments Agent Office 1
 └─ Agent: Acme Payments Agent Office 2
```

Each Agent branch resolves to its own Corporate Entity and Master Merchant structure so merchants can be boarded under the appropriate Master Merchant.

### Merchant ownership

Merchants are created under the Master Merchant record.

The Master Merchant is the partner record that owns the merchant portfolio for that hierarchy branch. Even when the visible commercial relationship starts at the ISO, Agent, or Corporate Entity level, the hierarchy must resolve to a Master Merchant before merchants can be boarded underneath it.

### When to use this model

Use the advanced partner hierarchy only when Bead has confirmed that the partner relationship requires one or more of the following:

| Scenario                                       | Example                                                                      |
| ---------------------------------------------- | ---------------------------------------------------------------------------- |
| Super-ISO or ISO structure                     | A top-level ISO manages multiple offices or sub-organizations.               |
| Regional Agent organization                    | Each Agent represents a regional office or sales group.                      |
| Boarding platform on behalf of another partner | A software provider boards merchants for a super-ISO or reseller.            |
| Separate merchant portfolios                   | Merchants need to roll up under different Agent or Master Merchant branches. |

### When not to use this model

Do not use the advanced hierarchy for standard merchant onboarding unless Bead has instructed you to do so.

Most partners should continue using the standard merchant onboarding and entity management flow. Adding ISO, Agent, Corporate Entity, or Master Merchant records when they are not needed can make reporting, permissions, and merchant ownership harder to manage.

### Best practice

Create the highest-level partner record Bead has instructed you to create, then use the automatically created downstream records.

Do not manually recreate the downstream hierarchy unless Bead has specifically instructed you to do so. Before adding new partner branches, confirm the intended parent partner ID and target hierarchy with Bead.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/reference-guide/core-concepts/advanced-partner-hierarchy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.