> 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/merchant-management/update-merchant.md).

# Update Merchant

Use these endpoints to submit, approve, and track requests to update a merchant record after KYB approval. Update requests go through an approval workflow before changes are applied, and support scheduled and time-limited updates.

#### How update requests work

An update request captures a proposed change to a merchant record. Rather than applying changes directly, the request enters an approval queue. Once approved, Bead applies the changes automatically. If `effectiveAt` is set, the change applies at the scheduled time. If `expiresAt` is set, the change is reverted when that time passes, with one exception: `expiresAt` does not revert a split funding enrollment. See [Split funding enrollment](#split-funding-enrollment) below.

This workflow is appropriate for changes to merchant details, fee configuration, merchant status, pinned status, split funding enrollment, or removal requests.

#### Endpoints

```
POST /Merchants/{merchantId}/update-requests
GET  /Merchants/{merchantId}/update-requests
GET  /Merchants/{merchantId}/update-requests/{requestId}
POST /Merchants/{merchantId}/update-requests/{requestId}/submit
POST /Merchants/{merchantId}/update-requests/{requestId}/approve
POST /Merchants/{merchantId}/update-requests/{requestId}/reject
POST /Merchants/{merchantId}/update-requests/{requestId}/cancel
```

***

#### Create Update Request

Submits a new update request for a merchant. Set `submit: true` to enter the request into the approval queue immediately. Set `submit: false` to create the request in DRAFT status for later review or submission via the separate submit endpoint.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

A partner API key can create, submit, and approve an update request for any merchant in its own hierarchy, including a split funding enrollment change, and can approve its own request. A terminal API key cannot call this endpoint and receives `403 Forbidden`.

**Path parameter**

| Name       | Type   | Required | Description                       |
| ---------- | ------ | -------- | --------------------------------- |
| merchantId | string | Yes      | The ID of the merchant to update. |

**Request body**

| Field           | Type                 | Required | Description                                                                                                                                                              |
| --------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| submit          | boolean              | Yes      | If true, the request is submitted for approval immediately. If false, the request is created in DRAFT status.                                                            |
| precedence      | integer              | Yes      | Priority level used when multiple update requests have overlapping time windows. Higher values take priority. Default is 100.                                            |
| changes         | object               | Yes      | The changes to apply to the merchant. See changes object below.                                                                                                          |
| justification   | string               | No       | Reason for the requested change. Recorded on the request and visible to the approver. Use this for an audit-trail note such as "Enrolling in the split funding program." |
| clientReference | string               | No       | Optional reference string for external tracking.                                                                                                                         |
| effectiveAt     | string (RFC3339 UTC) | No       | When the changes should take effect. If omitted, changes apply immediately upon approval.                                                                                |
| expiresAt       | string (RFC3339 UTC) | No       | When the changes should expire and be reverted. Optional. Does not revert a split funding enrollment, see below.                                                         |

**Changes object**

| Field                   | Type    | Description                                                                                                                      |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| merchantDetails         | object  | Updated merchant profile fields such as company name, description, or contact information.                                       |
| fee                     | object  | Updated fee configuration for the merchant.                                                                                      |
| status                  | string  | Updated merchant status. Accepts a valid merchant status value.                                                                  |
| setPinned               | boolean | Sets the pinned status of the merchant account.                                                                                  |
| setRebateProgramEnabled | boolean | Enrolls or removes the merchant from the [Split Funding Program](/split-funding.md). `true` enrolls; `false` removes. See below. |
| requestRemoval          | boolean | Requests soft deletion of the merchant and its terminals and locations.                                                          |
| removalReason           | string  | Reason for the removal request. Required when requestRemoval is true.                                                            |

#### Split funding enrollment

Enrollment in the [Split Funding Program](/split-funding.md) is a single boolean change sent through the same request and approve flow as any other merchant update. The field is named `setRebateProgramEnabled` on the wire.

* `true` enrolls the merchant. Once approved, the merchant can accept a split funding block on payment creation. See [Split Funding Program](/split-funding.md) for the full field reference and validation rules.
* `false` removes the merchant from the program. This stops new split funding payments. It does not affect payments already taken, in-flight settlements, or amounts already assessed for partner distribution.

> **`expiresAt` does not revert this change.** Unlike other update-request changes, a split funding enrollment is not automatically reverted when `expiresAt` passes. If you need to remove a merchant from the program on a schedule, submit an explicit `setRebateProgramEnabled: false` request rather than relying on `expiresAt`.

Enrollment does not validate the partner payout setup. The representing merchant record, its bank details, its per-tender fee rules and its status are all checked when the first distribution runs, not here. See [Partner distributions](/split-funding.md#partner-distributions).

**Example request: general merchant update**

```bash
curl -X POST "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests" \
  -H "X-Api-Key: {adminApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true,
    "precedence": 100,
    "clientReference": "your-internal-ref-001",
    "effectiveAt": null,
    "expiresAt": null,
    "changes": {
      "merchantDetails": {
        "companyName": "Acme Coffee Roasters Inc"
      }
    }
  }'
```

**Example request: split funding enrollment**

```bash
curl -X POST "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests" \
  -H "X-Api-Key: {partnerApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true,
    "precedence": 100,
    "justification": "Enrolling in the split funding program",
    "changes": {
      "setRebateProgramEnabled": true
    }
  }'
```

**Successful response, 200**

```json
{
  "requestId": "ureq_abc123",
  "merchantId": "mer_123123",
  "clientReference": "your-internal-ref-001",
  "status": "submitted",
  "requesterId": "user_ab12",
  "createdAt": "2025-07-01T12:00:00Z"
}
```

**Response fields**

| Field           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| requestId       | The unique ID of the update request. Store this to track the request status. |
| merchantId      | The ID of the merchant this request applies to.                              |
| clientReference | The client reference you supplied, if any.                                   |
| status          | The current status of the request. See status lifecycle below.               |
| requesterId     | The ID of the user who created the request.                                  |
| createdAt       | Timestamp when the request was created.                                      |

**Request status lifecycle**

| Status    | Meaning                                                                             |
| --------- | ----------------------------------------------------------------------------------- |
| draft     | The request was created with submit: false and has not been submitted for approval. |
| submitted | The request is in the approval queue.                                               |
| approved  | The request has been approved and is pending application.                           |
| applied   | The changes have been applied to the merchant record.                               |
| rejected  | The request was not approved. No changes were applied.                              |
| expired   | The request reached its expiresAt time and was reverted or not applied.             |
| cancelled | The request was cancelled before approval or application.                           |

**Error responses**

| Code | Condition                                                                                                             |
| ---- | --------------------------------------------------------------------------------------------------------------------- |
| 400  | Request body is missing required fields or contains invalid values.                                                   |
| 401  | Missing or invalid API key.                                                                                           |
| 403  | Authenticated but not permitted to submit update requests for this merchant. A terminal API key always receives this. |
| 404  | Merchant does not exist or is not visible to your key.                                                                |

#### Submit a Draft Request

Submits a request that was created with `submit: false`, moving it from `draft` into the approval queue.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

**Path parameters**

| Name       | Type   | Required | Description                  |
| ---------- | ------ | -------- | ---------------------------- |
| merchantId | string | Yes      | The ID of the merchant.      |
| requestId  | string | Yes      | The ID of the draft request. |

**Example request**

```bash
curl -X POST \
  "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests/{requestId}/submit" \
  -H "X-Api-Key: {adminApiKey}"
```

#### Approve a Request

Approves a `submitted` request. If `effectiveAt` was not set on the request, changes apply immediately.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

A partner API key can approve its own request for a merchant in its hierarchy. Approval is not restricted to a different actor than the requester.

**Path parameters**

| Name       | Type   | Required | Description                       |
| ---------- | ------ | -------- | --------------------------------- |
| merchantId | string | Yes      | The ID of the merchant.           |
| requestId  | string | Yes      | The ID of the request to approve. |

**Request body**

| Field             | Type   | Required | Description                                   |
| ----------------- | ------ | -------- | --------------------------------------------- |
| reason            | string | No       | Optional note recorded with the approval.     |
| approverReference | string | No       | Optional external reference for the approver. |

**Example request**

```bash
curl -X POST \
  "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests/{requestId}/approve" \
  -H "X-Api-Key: {adminApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Approved for split funding program"
  }'
```

#### Reject a Request

Rejects a `submitted` request. No changes are applied.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

**Path parameters**

| Name       | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| merchantId | string | Yes      | The ID of the merchant.          |
| requestId  | string | Yes      | The ID of the request to reject. |

**Request body**

| Field             | Type   | Required | Description                                   |
| ----------------- | ------ | -------- | --------------------------------------------- |
| reason            | string | No       | Optional note recorded with the rejection.    |
| approverReference | string | No       | Optional external reference for the approver. |

#### Cancel a Request

Cancels a request before it has been approved or applied.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

**Path parameters**

| Name       | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| merchantId | string | Yes      | The ID of the merchant.          |
| requestId  | string | Yes      | The ID of the request to cancel. |

#### Get a Single Request

Returns one update request by ID.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

**Path parameters**

| Name       | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| merchantId | string | Yes      | The ID of the merchant. |
| requestId  | string | Yes      | The ID of the request.  |

#### List Update Requests

Returns a paginated list of update requests for a merchant, with optional filters by status, date range, and search term.

**Authentication**

```
X-Api-Key: {adminApiKey}
```

**Path parameter**

| Name       | Type   | Required | Description                                               |
| ---------- | ------ | -------- | --------------------------------------------------------- |
| merchantId | string | Yes      | The ID of the merchant whose update requests to retrieve. |

**Query parameters**

| Parameter     | Type             | Description                                                                           |
| ------------- | ---------------- | ------------------------------------------------------------------------------------- |
| Statuses      | array of strings | Filter by one or more request statuses. Returns the union across all supplied values. |
| Search        | string           | Free text search across merchant name, request ID, and merchant display ID (MID).     |
| From          | string           | Filter by requests submitted on or after this date.                                   |
| To            | string           | Filter by requests submitted on or before this date.                                  |
| Page          | integer          | Page number. Starts at 1.                                                             |
| PageSize      | integer          | Number of results per page.                                                           |
| SortBy        | string           | Field to sort by.                                                                     |
| SortDirection | string           | Sort direction: asc or desc.                                                          |

**Example request**

```bash
curl -X GET \
  "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests?Statuses=submitted&Page=1&PageSize=25" \
  -H "X-Api-Key: {adminApiKey}"
```

**Successful response, 200**

```json
{
  "data": [
    {
      "requestId": "ureq_abc123",
      "merchantId": "mer_123123",
      "clientReference": "your-internal-ref-001",
      "status": "submitted",
      "requesterId": "user_ab12",
      "createdAt": "2025-07-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}
```

**Response fields**

| Field | Description                                                                                |
| ----- | ------------------------------------------------------------------------------------------ |
| data  | Array of update request objects. Each object follows the same schema as the POST response. |
| total | Total number of matching requests across all pages.                                        |
| page  | The current page number returned.                                                          |

**Error responses**

| Code | Condition                                                                  |
| ---- | -------------------------------------------------------------------------- |
| 401  | Missing or invalid API key.                                                |
| 403  | Authenticated but not permitted to view update requests for this merchant. |
| 404  | Merchant does not exist or is not visible to your key.                     |

#### Best practices

Store `requestId` when creating a request so you can look it up or reference it later.

Use `clientReference` to tie a Bead update request back to an action or record in your own system.

Use `justification` to record why a change was requested. This is the field the split funding enrollment example uses, and it is good practice for any change an approver did not originate.

Use `submit: false` when you want to stage a change for review before it enters the approval queue, then call the submit endpoint when it is ready.

Use `effectiveAt` when a change needs to take effect at a specific future time rather than immediately upon approval.

Use `expiresAt` for temporary changes that should be automatically reverted, except for split funding enrollment, which `expiresAt` does not revert. Submit an explicit `false` request to remove a merchant from the Split Funding Program.

Use the `Statuses` filter when listing requests to focus on requests that are pending action such as submitted or approved.

Check `status` after submitting to confirm whether the request entered the approval queue or requires additional action.

#### Related pages

* [Get Merchant](/entity-management/merchant-management/get-merchant.md)
* [List Merchants](/entity-management/merchant-management/list-merchants.md)
* [Split Funding Program](/split-funding.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/merchant-management/update-merchant.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.