> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/partner-management.md).

# Partner Management

Use Partner Management APIs to create and update partner records. Partner records sit above merchants in the Bead entity model and are used to organize merchant ownership, reporting, permissions, and hierarchy.

Most integrations do not need to create partner hierarchy records directly. Use these APIs only when Bead has confirmed that your integration should manage partner records programmatically.

**Where Partner Management fits**

For most integrations, the entity model is:

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

For advanced ISO, reseller, or boarding-platform configurations, the partner level may include an expanded hierarchy:

```
ISO → Agent → Corporate Entity → Master Merchant → Merchant
```

For ISO, Agent, Corporate Entity, and Master Merchant behavior, see [Advanced Partner Hierarchy](/reference-guide/core-concepts/advanced-partner-hierarchy.md).

**Authentication**

All Partner Management endpoints use API key authentication.

| Header      | Value              |
| ----------- | ------------------ |
| `X-Api-Key` | `{adminApiKey}`    |
| `Accept`    | `application/json` |

For write operations, also include:

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

**List partners**

Returns a paginated list of partner records. Use this endpoint to browse the partner hierarchy or locate a specific partner before creating or updating records.

```http
GET /Partners/all
```

**Query parameters**

| Parameter       | Type    | Required | Description                                                                 |
| --------------- | ------- | -------- | --------------------------------------------------------------------------- |
| `PartnerIds`    | array   | No       | Filter by specific partner IDs                                              |
| `IsEnabled`     | boolean | No       | Filter by enabled status                                                    |
| `Type`          | string  | No       | Filter by partner type: `iso`, `agent`, `corporateEntity`, `masterMerchant` |
| `Search`        | string  | No       | Search by name, email, or phone number                                      |
| `SortBy`        | string  | No       | One of: `Created`, `Updated`, `IsEnabled`, `PartnerType`, `Name`            |
| `SortDirection` | string  | No       | `asc` or `desc`                                                             |
| `Page`          | integer | No       | Page number, zero-indexed                                                   |
| `PageSize`      | integer | No       | Results per page, max `100`                                                 |

**Example request**

```bash
curl -X GET "https://api.test.devs.beadpay.io/Partners/all?Page=0&PageSize=50" \
-H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                      |
| ---- | ------------------------------ |
| 200  | Partners returned successfully |
| 401  | Missing or invalid API key     |
| 403  | Not permitted to list partners |

**Get a partner**

Retrieves a specific partner record.

```http
GET /Partners/{id}
```

`id` is the ID of the partner to retrieve.

**Example request**

```bash
curl -X GET "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
-H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                            |
| ---- | ------------------------------------ |
| 200  | Partner returned successfully        |
| 401  | Missing or invalid API key           |
| 403  | Not permitted to access this partner |
| 404  | Partner not found                    |

**Get a partner's fee schedule**

Returns the partner's **effective** fee schedule — the resolved rates a merchant boarded under this partner is priced against.

```http
GET /Partners/{id}/fee-schedule
```

`id` is the ID of the partner to retrieve the fee schedule for.

**How resolution works**

A partner's fee schedule is held by its representing merchant. A partner without a representing merchant of its own inherits the schedule of its nearest ancestor that has one.

Each fee in the response carries two rates:

* `sellRate` — what the resolved partner charges.
* `buyRate` — what the partner pays, which is always its parent account's `sellRate`. This is computed by Bead; it is never submitted.

A fee is included in the response if either side is configured — for example, an inherited `buyRate` can appear even before the partner's own `sellRate` has been set. A side with no configured rate is returned as `null`, never `0`.

**Why this matters for onboarding**

This schedule's `sellRate` values are the **floor** for merchant-level pricing: onboarding rejects a merchant `feeInformation` sell rate that falls below the resolved partner fee schedule. Call this endpoint before assembling `feeInformation` for [Submit Application](/onboarding/submit-application.md) — see [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) — so you know the floor before you price a merchant, rather than discovering it as a validation failure. See also [Field Validation Rules → Pricing and tenders](/onboarding/field-validation-rules.md).

**Example request**

```bash
curl -X GET "https://api.test.devs.beadpay.io/Partners/{partnerId}/fee-schedule" \
-H "X-Api-Key: {adminApiKey}"
```

**Response fields**

| Field                      | Type             | Description                                                                                                                                                                                |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `partnerId`                | string           | The partner the schedule was requested for.                                                                                                                                                |
| `resolvedFromPartnerId`    | string           | The partner whose representing merchant supplied the sell rates — the requested partner itself, or the nearest ancestor with a representing merchant when the partner has none of its own. |
| `representingMerchantId`   | string           | The representing merchant holding the schedule.                                                                                                                                            |
| `achSettlementFixedFee`    | object or `null` | Settlement ACH fixed fee — `sellRate`, `buyRate`, `isBilledByPartner`.                                                                                                                     |
| `settlementReturnFixedFee` | object or `null` | Settlement return fixed fee — `sellRate`, `buyRate`, `isBilledByPartner`.                                                                                                                  |
| `monthlyMaintenanceFee`    | object or `null` | Monthly maintenance fee — `sellRate`, `buyRate`, `isBilledByPartner`.                                                                                                                      |
| `cryptoFees`               | array or `null`  | One entry per configured crypto tender: `tenderType`, `transactionRate`, `perItemFee`.                                                                                                     |
| `digitalWalletsFees`       | array or `null`  | One entry per configured digital wallet tender: `tenderType`, `transactionRate`, `perItemFee`.                                                                                             |

Each `transactionRate` and `perItemFee` is itself a `{ sellRate, buyRate, isBilledByPartner }` object, following the same null-if-unconfigured rule as the top-level fixed fees.

> **Note:** unlike `feeInformation.digitalWalletsFees` on the onboarding endpoints, entries here are not split by `paymentLocationType` (`inStore` / `online`) — the fee schedule reflects one resolved rate per tender, not per channel.

**Response codes**

| Code | Condition                                                        |
| ---- | ---------------------------------------------------------------- |
| 200  | Fee schedule returned successfully                               |
| 401  | Missing or invalid API key                                       |
| 403  | Not permitted to access this partner                             |
| 404  | Neither the partner nor any ancestor has a representing merchant |

**Add a partner**

Creates a child partner under an existing parent partner.

```http
POST /Partners/{parentId}/partners
```

`parentId` is the ID of the partner that should own the new partner record.

**Automatic downstream creation**

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

| Partner type added | Records Bead automatically creates       |
| ------------------ | ---------------------------------------- |
| `iso`              | Agent, Corporate Entity, Master Merchant |
| `agent`            | Corporate Entity, Master Merchant        |
| `corporateEntity`  | Master Merchant                          |
| `masterMerchant`   | None                                     |

Create the highest-level partner record Bead instructed you to create, then use the created hierarchy to identify the downstream Master Merchant record. Do not manually recreate the downstream hierarchy unless Bead has specifically instructed you to do so.

**Request body**

```json
{
"partnerType": "iso",
"name": "Acme Payments",
"email": "operations@example.com",
"phoneNumber": "+15555550100",
"feeInfo": {
"crypto": {
"feeFactor": 0,
"fixedFee": 0
},
"card": null
},
"tenderTypes": ["usdcBase", "bitcoin"],
"maxTransactionAmount": 10000
}
```

In this example, adding `Acme Payments` as an ISO creates the required downstream Agent, Corporate Entity, and Master Merchant records automatically.

**Request fields**

| Field                  | Type   | Required | Description                                                            |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `partnerType`          | string | Yes      | Type to create: `iso`, `agent`, `corporateEntity`, or `masterMerchant` |
| `name`                 | string | Yes      | Partner display name. Max 256 characters                               |
| `feeInfo`              | object | Yes      | Partner fee configuration                                              |
| `tenderTypes`          | array  | Yes      | Tender types enabled for the partner                                   |
| `email`                | string | No       | Partner contact email                                                  |
| `phoneNumber`          | string | No       | Partner contact phone number                                           |
| `maxTransactionAmount` | number | No       | Maximum transaction amount for this partner                            |

Note: `root` may appear as a `partnerType` value in read responses. It cannot be used when creating a partner.

**Example request**

```bash
curl -X POST "https://api.test.devs.beadpay.io/Partners/{parentId}/partners" \
-H "X-Api-Key: {adminApiKey}" \
-H "Content-Type: application/json" \
-d '{
"partnerType": "iso",
"name": "Acme Payments",
"email": "operations@example.com",
"phoneNumber": "+15555550100",
"feeInfo": {
"crypto": { "feeFactor": 0, "fixedFee": 0 },
"card": null
},
"tenderTypes": ["usdcBase", "bitcoin"],
"maxTransactionAmount": 10000
}'
```

**Response codes**

| Code | Condition                                           |
| ---- | --------------------------------------------------- |
| 200  | Partner created successfully                        |
| 201  | Partner created successfully                        |
| 202  | Creation accepted for processing                    |
| 400  | Invalid fields or validation error                  |
| 401  | Missing or invalid API key                          |
| 403  | Not permitted to create a partner under this parent |
| 409  | Conflict — duplicate or constraint violation        |

**Add another Agent branch**

If Bead has instructed you to create an additional Agent under an existing ISO, create the Agent as a child partner of the ISO. Bead automatically creates the Corporate Entity and Master Merchant records under that Agent branch.

```json
{
"partnerType": "agent",
"name": "Acme Payments Agent Office 1",
"email": "operations@example.com",
"phoneNumber": "+15555550100",
"feeInfo": {
"crypto": {
"feeFactor": 0,
"fixedFee": 0
},
"card": null
},
"tenderTypes": ["usdcBase", "bitcoin"],
"maxTransactionAmount": 10000
}
```

**Edit a partner**

Updates an existing partner record.

```http
PUT /Partners/{id}
```

`id` is the ID of the partner to update.

**Request body**

```json
{
"name": "Acme Payments Agent Office 1",
"email": "operations@example.com",
"phoneNumber": "+15555550100",
"feeInfo": {
"crypto": {
"feeFactor": 0,
"fixedFee": 0
},
"card": null
},
"tenderTypes": ["usdcBase", "bitcoin"],
"maxTransactionAmount": 10000
}
```

**Request fields**

| Field                  | Type   | Required | Description                                 |
| ---------------------- | ------ | -------- | ------------------------------------------- |
| `name`                 | string | Yes      | Partner display name. Max 256 characters    |
| `feeInfo`              | object | Yes      | Partner fee configuration                   |
| `tenderTypes`          | array  | Yes      | Tender types enabled for the partner        |
| `email`                | string | No       | Partner contact email                       |
| `phoneNumber`          | string | No       | Partner contact phone number                |
| `maxTransactionAmount` | number | No       | Maximum transaction amount for this partner |

**Example request**

```bash
curl -X PUT "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
-H "X-Api-Key: {adminApiKey}" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Payments Agent Office 1",
"email": "operations@example.com",
"phoneNumber": "+15555550100",
"feeInfo": {
"crypto": { "feeFactor": 0, "fixedFee": 0 },
"card": null
},
"tenderTypes": ["usdcBase", "bitcoin"],
"maxTransactionAmount": 10000
}'
```

**Response codes**

| Code | Condition                                    |
| ---- | -------------------------------------------- |
| 200  | Partner updated successfully                 |
| 202  | Update accepted for processing               |
| 204  | Update completed, no response body           |
| 400  | Invalid fields or validation error           |
| 401  | Missing or invalid API key                   |
| 403  | Not permitted to update this partner         |
| 404  | Partner not found                            |
| 409  | Conflict — duplicate or constraint violation |

**Delete a partner**

Removes a partner record.

```http
DELETE /Partners/{id}
```

`id` is the ID of the partner to delete.

**Example request**

```bash
curl -X DELETE "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
-H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                                  |
| ---- | ------------------------------------------ |
| 204  | Partner deleted successfully               |
| 400  | Invalid request or business rule violation |
| 401  | Missing or invalid API key                 |
| 403  | Not permitted to delete this partner       |
| 404  | Partner not found                          |

**Notes**

Partner creation and updates can affect downstream merchant ownership, reporting, permissions, tender availability, and which Master Merchant a merchant should be boarded under. Before adding or editing partner records, confirm the intended parent partner ID and target hierarchy branch with Bead.

**Related pages**

* [Advanced Partner Hierarchy](/reference-guide/core-concepts/advanced-partner-hierarchy.md)
* [Merchant Management](/entity-management/merchant-management.md)
* [List Merchants](/entity-management/merchant-management/list-merchants.md)
* [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md)
* [Field Validation Rules](/onboarding/field-validation-rules.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/entity-management/partner-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.